1pod::Prima::image-load(U3s)er Contributed Perl Documentatpioodn::Prima::image-load(3)
2
3
4

NAME

6       Prima::image-load - Using image subsystem
7

DESCRIPTION

9       Details on image subsystem - image loading, saving, and codec
10       managements
11

Loading

13   Simple loading
14       Simplest case, loading a single image would look like:
15
16               my $x = Prima::Image-> load( 'filename.duf');
17               die "$@" unless $x;
18
19       Image functions can work being either invoked from package, or from
20       existing Prima::Image object, in latter case the caller object itself
21       is changing. The code above could be also written as
22
23               my $x = Prima::Image-> create;
24               die "$@" unless $x-> load( 'filename.duf');
25
26       In both cases $x contains image data upon success.  Error is returned
27       into $@ variable ( see perldoc perlvar for more info).
28
29   Loading from stream
30       "Prima::Image" can also load image by reading from a stream:
31
32               open FILE, 'a.jpeg' or die "Cannot open:$!";
33               binmode FILE;
34               my $x = Prima::Image-> load( \*FILE);
35               die "$@" unless $x;
36
37   Multiframe loading
38       Multiframe load call can be also issued in two ways:
39
40               my @x = Prima::Image-> load( 'filename.duf', loadAll => 1);
41               die "$@" unless $x[-1];
42
43               my $x = Prima::Image-> create;
44               my @x = $x-> load( 'filename.duf', loadAll => 1);
45               die "$@" unless $x[-1];
46
47       In second case, the content of the first frame comes to $x and $x[0].
48       Sufficient check for error is whether last item of a returned array is
49       defined. This check works also if an empty array is returned.  Only
50       this last item can be an undefined value, others are guaranteed to be
51       valid objects.
52
53       Multiframe syntax is expressed in a set of extra hash keys.  These keys
54       are:
55
56       loadAll
57           Request for loading all frames that can be read from a file.
58           Example:
59
60                   loadAll => 1
61
62       index
63           If present, returns a single frame with index given.  Example:
64
65                   index => 8
66
67       map Contains an anonymous array of frame indices to load.  Valid
68           indices are above zero, negative ones can't be counted in a way
69           perl array indices are. Example:
70
71                    map => [0, 10, 15..20]
72
73   Querying extra information
74       By default Prima loads image data and palette only. For any other
75       information that can be loaded, anonymous hash 'extras' can be defined.
76       To notify a codec that this extra information is desired, loadExtras
77       boolean value is used.  Example:
78
79               my $x = Prima::Image-> load( $f, loadExtras => 1);
80               die "$@" unless $x;
81               for ( keys %{$x-> {extras}}) {
82                  print " $_ : $x->{extras}->{$_}\n";
83               }
84
85       The code above loads and prints extra information read from a file.
86       Typical output, for example, from a gif codec based on libgif would
87       look like:
88
89           codecID : 1
90           transparentColorIndex : 1
91           comment : created by GIMP
92           frames : 18
93
94       'codecID' is a Prima-defined extra field, which is an index of the
95       codec which have loaded the file. This field's value is useful for
96       explicit indication of codec on the save request.
97
98       'frames' is also a Prima-defined extra field, with integer value set to
99       a number of frames in the image. It might be set to -1, signaling that
100       codec is incapable of quick reading of the frame count.  If, however,
101       it is necessary to get actual frame count, a 'wantFrames' profile
102       boolean value should be set to 1 - then frames is guaranteed to be set
103       to a 0 or positive value, but the request may take longer time,
104       especially on a large file with sequential access. Real life example is
105       a gif file with more than thousand frames. 'wantFrames' is useful in
106       null load requests.
107
108   Multiprofile loading requests
109       The parameters that are accepted by load, are divided into several
110       categories - first, those that apply to all loading process and those
111       who apply only to a particular frame. Those who are defined by Prima,
112       are enumerated above - loadExtras, loadAll etc. Only loadExtras,
113       noImageData, noIncomplete and iconUnmask are applicable to a frame,
114       other govern the loading process. A codec may as well define its own
115       parameters, however it is not possible to tell what parameter belongs
116       to what group - this information is to be found in codec documentation;
117
118       The parameters that applicable to any frame, can be specified
119       separately to every desirable frame in single call. For that purpose,
120       parameter 'profiles' is defined. 'profiles' is expected to be an
121       anonymous array of hashes, each hash where corresponds to a request
122       number. Example:
123
124               $x-> load( $f, loadAll => 1, profiles => [
125                    {loadExtras => 0},
126                    {loadExtras => 1},
127               ]);
128
129       First hash there applies to frame index 0, second - to frame index 1.
130       Note that in code
131
132               $x-> load( $f,
133                  map => [ 5, 10],
134                  profiles => [
135                    {loadExtras => 0},
136                    {loadExtras => 1},
137               ]);
138
139       first hash applies to frame index 5, and second - to frame index 10.
140
141   Null load requests
142       If it is desired to peek into image, reading type and dimensions only,
143       one should set 'noImageData' boolean value to 1. Using 'noImageData',
144       empty objects with read type are returned, and with extras 'width' and
145       'height' set to image dimensions. Example:
146
147               $x-> load( $f, noImageData => 1);
148               die "$@" unless $x;
149               print $x-> {extras}-> {width} , 'x' , $x-> {extras}-> {height}, 'x',
150                  $x-> type & im::BPP, "\n";
151
152       Some information about image can be loaded even without frame loading -
153       if the codec provides such a functionality. This is the only request
154       that cannot be issued on a package:
155
156               $x-> load( $f, map => [], loadExtras => 1);
157
158       Since no frames are required to load, an empty array is returned upon
159       success and an array with one undefined value on failure.
160
161   Using Prima::Image descendants
162       If Prima needs to create a storage object, it is by default
163       Prima::Image, or a class name of an caller object, or a package the
164       request was issued on. This behavior can be altered using parameter
165       'className', which defines the class to be used for the frame.
166
167               my @x = Prima::Image-> load( $f,
168                   map => [ 1..3],
169                   className => 'Prima::Icon',
170                   profiles => [
171                       {},
172                       { className => 'Prima::Image' },
173                       {}
174                   ],
175
176       In this example @x will be ( Icon, Image, Icon) upon success.
177
178       When loading to an Icon object, the default toolkit action is to build
179       the transparency mask based on image data. When it is not the desired
180       behavior, e.g., there is no explicit knowledge of image, but the image
181       may or may not contain transparency information, "iconUnmask" boolean
182       option can be used. When set to a "true" value, and the object is
183       "Prima::Icon" descendant, "Prima::Icon::autoMasking" is set to
184       "am::None" prior to the file loading. By default this options is turned
185       off.
186
187   Loading with progress indicator
188       Some codecs (PNG,TIFF,JPEG) can notify the caller as they read image
189       data.  For this purpose, "Prima::Image" has two events, "onHeaderReady"
190       and "onDataReady". If either (or both) are present on image object that
191       is issuing load call, and the codec supports progressive loading, these
192       events are called.  "onHeaderReady" is called when image header data is
193       acquired, and empty image with the dimensions and pixel type is
194       allocated. "onDataReady" is called whenever a part of image is ready
195       and is loaded in the memory of the object; the position and dimensions
196       of the loaded area is reported also. The format of the events is:
197
198           onHeaderReady $OBJECT
199           onDataReady   $OBJECT, $X, $Y, $WIDTH, $HEIGHT
200
201       "onHeaderReady" is called only once, but "onDataReady" is called as
202       soon as new image data is available. To reduce frequency of these
203       calls, that otherwise would be issued on every scanline loaded, "load"
204       has parameter "eventDelay", a number of seconds, which limits event
205       rate. The default "eventDelay" is 0.1 .
206
207       The handling on "onDataReady" must be performed with care. First, the
208       image must be accessed read-only, which means no transformations with
209       image size and type are allowed. Currently there is no protection for
210       such actions ( because codec must perform these ), so a crash will most
211       surely issue.  Second, loading and saving of images is not in general
212       reentrant, and although some codecs are reentrant, loading and saving
213       images inside image events is not recommended.
214
215       There are two techniques to display partial image as it loads. All of
216       these share overloading of "onHeaderReady" and "onDataReady". The
217       simpler is to call "put_image" from inside "onDataReady":
218
219               $i = Prima::Image-> new(
220                       onDataReady => sub {
221                               $progress_widget-> put_image( 0, 0, $i);
222                       },
223               );
224
225       but that will most probably loads heavily underlying OS-dependent
226       conversion of image data to native display bitmap data. A more smarter,
227       but more complex solution is to copy loaded (and only loaded) bits to a
228       preexisting device bitmap:
229
230               $i = Prima::Image-> new(
231                       onHeaderReady => sub {
232                               $bitmap = Prima::DeviceBitmap-> new(
233                                       width    => $i-> width,
234                                       height   => $i-> height,
235                               ));
236                       },
237                       onDataReady => sub {
238                               my ( $i, $x, $y, $w, $h) = @_;
239                               $bitmap-> put_image( $x, $y, $i-> extract( $x, $y, $w, $h));
240                       },
241               );
242
243       The latter technique is used by "Prima::ImageViewer" when it is setup
244       to monitor image loading progress. See "watch_load_progress" in
245       Prima::ImageViewer for details.
246
247   Truncated files
248       By default, codecs are not specified whether they would fail on
249       premature end of file or omit the error and return truncated image.
250       "noIncomplete" boolean flag tells that a codec must always fail if the
251       image cannot be red in full. It is off by default. If indeed the codec
252       detected that the file was incomplete, it sets "truncated" error string
253       in the "extras" profile, if "loadExtras" was requested.
254

Saving

256   Simple saving
257       Typical saving code will be:
258
259          die "$@" unless $x-> save( 'filename.duf');
260
261       Upon a single-frame invocation save returns 1 upon success an 0 on
262       failure.  Save requests also can be performed with package syntax:
263
264          die "$@" unless Prima::Image-> save( 'filename.duf',
265              images => [ $x]);
266
267   Saving to a stream
268       Saving to a stream requires explicit "codecID" to be supplied. When an
269       image is loaded with "loadExtras", this field is always present on the
270       image object, and is an integer that selects image encoding format.
271
272          my @png_id =
273             map  { $_-> {codecID} }
274             grep { $_-> {fileShortType} =~ /^png$/i }
275             @{ Prima::Image-> codecs };
276          die "No png codec installed" unless @png_id;
277
278          open FILE, "> a.png" or die "Cannot save:$!";
279          binmode FILE;
280          $image-> save( \*FILE, codecID => $png_id[0])
281             or die "Cannot save:$@";
282
283   Multiframe saving
284       In multiframe invocation save returns number of successfully saved
285       frames.  File is erased though, if error occurred, even after some
286       successfully written frames.
287
288           die "$@" if scalar(@images) > Prima::Image-> save( $f,
289              images => \@images);
290
291   Saving extras information
292       All information, that is found in object hash reference 'extras', is
293       assumed to be saved as an extra information. It is a codec's own
294       business how it reacts on invalid and/or inacceptable information - but
295       typical behavior is that keys that were not recognized by the codec
296       just get ignored, and invalid values raise an error.
297
298              $x-> {extras}-> {comments} = 'Created by Prima';
299              $x-> save( $f);
300
301   Selecting a codec
302       Extras field 'codecID', the same one that is defined after load
303       requests, selects explicitly a codec for an image to handle. If the
304       codec selected is incapable of saving an error is returned. Selecting a
305       codec is only possible with the object-driven syntax, and this
306       information is never extracted from objects but passed to 'images'
307       array instead.
308
309              $x-> {extras}-> {codecID} = 1;
310              $x-> save( $f);
311
312       Actual correspondence between codecs and their indices is described
313       latter.
314
315       NB - if codecID is not given, codec is selected by the file extension.
316
317   Type conversion
318       Codecs usually are incapable of saving images in all formats, so Prima
319       either converts an image to an appropriate format or signals an error.
320       This behavior is governed by profile key 'autoConvert', which is 1 by
321       default. 'autoConvert' can be present in image 'extras' structures.
322       With autoConvert set it is guaranteed that image will be saved, but
323       original image information may be lost. With autoConvert unset, no
324       information will be lost, but Prima may signal an error. Therefore
325       general-purpose save routines should be planned carefully. As an
326       example the "Prima::Dialog::ImageDialog::SaveImageDialog" code might be
327       useful.
328
329       When the conversion takes place, Image property 'conversion' is used
330       for selection of an error distribution algorithm, if down-sampling is
331       required.
332
333   Appending frames to an existing file
334       This functionality is under design, but the common outlines are already
335       set.  Profile key 'append' ( 0 by default ) triggers this behavior - if
336       it is set, then an append attempt is made.
337

Managing codecs

339       Prima provides single function, Prima::Image-> codecs, which returns an
340       anonymous array of hashes, where every hash entry corresponds to a
341       registered codec. 'codecID' parameter on load and save requests is
342       actually an index in this array. Indexes for a codecs registered once
343       never change, so it is safe to manipulate these numbers within single
344       program run.
345
346       Codec information that is contained in these hashes is divided into
347       following parameters:
348
349       codecID
350           Unique integer value for a codec, same as index of the codec entry
351           in results of "Prima::Image->codecs";
352
353       name
354           codec full name, string
355
356       vendor
357           codec vendor, string
358
359       versionMajor and versionMinor
360           usually underlying library versions, integers
361
362       fileExtensions
363           array of strings, with file extensions that are typical to a codec.
364           example: ['tif', 'tiff']
365
366       fileType
367           Description of a type of a file, that codec is designed to work
368           with.  String.
369
370       fileShortType
371           Short description of a type of a file, that codec is designed to
372           work with.  ( short means 3-4 characters ). String.
373
374       featuresSupported
375           Array of strings, with some features description that a codec
376           supports - usually codecs implement only a part of file format
377           specification, so it is always interesting to know, what part it
378           is.
379
380       module and package
381           Specify a perl module, usually inside Prima/Image directory into
382           Prima distribution, and a package inside the module. The package
383           contains some specific functions for work with codec-specific
384           parameters. Current implementation defines only ::save_dialog()
385           function, that returns a dialog that allows to change these
386           parameters. See "Prima::Dialog::ImageDialog::SaveImageDialog" for
387           details.  Strings, undefined if empty.
388
389       canLoad
390           1 if a codec can load images, 0 if not
391
392       canLoadStream
393           1 if a codec can load images from streams, 0 otherwise
394
395       canLoadMultiple
396           1 if a codec can handle multiframe load requests and load frames
397           with index more than zero. 0 if not.
398
399       canSave
400           1 if a codec can save images, 0 if not.
401
402       canSaveStream
403           1 if a codec can save images to streams, 0 otherwise
404
405       canSaveMultiple
406           Set if a codec can save more that one frame
407
408       canAppend
409           Set if a codec can append frames to an exising file
410
411       types
412           Array of integers - each is a combination of im:: flags, an image
413           type, which a codec is capable of saving. First type in list is a
414           default one; if image type that to be saved is not in that list,
415           the image will be converted to this default type.
416
417       loadInput
418           Hash, where keys are those that are accepted by Prima::Image->
419           load, and values are default values for these keys.
420
421       loadOutput
422           Array of strings, each of those is a name of extra information
423           entry in 'extras' hash.
424
425       saveInput
426           Hash, where keys are those that are accepted by Prima::Image->
427           save, and values are default values for these keys.
428
429       mime
430           array of strings, with file extensions that are typical to a codec.
431           example: ['image/xbm', 'image/x-bitmap']
432

API

434       This section describes parameters accepted and data returned by
435       "Prima::Image::load"
436
437   Common
438       Loading parameters
439
440       blending BOOLEAN = 1
441           Affects how to treat alpha channel bits, if any.
442
443           If set, mixes the alpha channel with background color in case if
444           loading to an image, or premultiplies color bits (either data or
445           palette) with alpha, if loading to icon. Note that saving back the
446           object will result in different image, but the object is ready to
447           be displayed immediately.
448
449           If unset, color and eventual alpha bits, if loaded to an icon, will
450           not be affected in any way. Note that saving back the object will
451           result in the same image, but the object is not ready to be
452           displayed immediately. See also: "premultiply_alpha" in
453           Prima::Image.
454
455       className STRING
456           When loading more than one image, this string is used to create
457           instances of image containers. By default the calling class is used
458           (i.e. "Prima::Image" or "Prima::Icon").
459
460       eventDelay INT
461           Specifies "onDataReady" event granularity in microseconds, if image
462           codec is capable of triggering this event.
463
464           Default: 100
465
466       iconUnmask BOOL
467           If set, "Prima::Icon::autoMasking" is set to "am::None" prior to
468           the file loading.
469
470           Default: false. Only actual for "Prima::Icon" loading.
471
472       index INT
473           When loading from a multiframe file, selects the frame index to
474           load.
475
476           Default: 0
477
478       map [INT]
479           When loading from a multiframe file, selects set of frame indexes
480           to load.
481
482           Default: undef
483
484       loadExtras BOOL
485           If set, all available extra information will be stored in
486           "{extras}" hash on the loaded object.
487
488           Default: false
489
490       loadAll BOOL
491           When loading from a multiframe file, selects that all frames are to
492           be loaded
493
494           Default: false
495
496       noImageData BOOL
497           When set, neither image data is not loaded, nor image dimensions
498           are changed (newly created images have size of 1x1). Instead,
499           "{extras}" contains "width" and "height" integers.
500
501           Default: false
502
503       noIncomplete BOOL
504           Affects the action when image is incomplete, truncated, etc.  If
505           set, signals an error. Otherwise no error is signalled and whatever
506           data could be recovered from the image are returned, and
507           "truncated" flag is set.
508
509           Default: false
510
511       profiles [HASH]
512           Array of hashes passed down to each frame in multiframe loads. Each
513           frame load request will be passed an individual hash, a result of
514           hash join of all profiles passed to "Image::load" and the nth hash
515           in the array.
516
517       wantFrames BOOL
518           Affects how the number of frames in a file is reported in "frames"
519           flag. If set, always scans the file for exact number. Otherwise it
520           is up to the codec to do that.
521
522           Default: false
523
524           See also: frames.
525
526       Load output
527
528       codecID INT
529           Indicates the internal codec ID used to load the image. Can be used
530           for "Image::save".
531
532       frames INT
533           If set to a positive integer, indicates number of frames in a file.
534           Otherwise signals that there are frames, but codec needs an
535           expensive scan to calculate the frames (and "wantFrames" set).
536
537       height INT
538           When "noImageData" is in action, contains image height.
539
540       truncated BOOL
541           When "noIncomplete" is in action, is set if image was truncated.
542           The value is the error string.
543
544       width INT
545           When "noImageData" is in action, contains image width.
546
547       Saving parameters
548
549       autoConvert BOOL
550           Affects the action when image cannot be stored in file format in
551           its existing pixel format.  If set, the system tries to convert
552           image into a pixel format understood by the selected codec. Fails
553           otherwise.
554
555           Default: true
556
557       codecID INT
558           Overrides codec selection based on filename extension.
559
560           Default: undef
561
562   BMP codec
563       BMP, the bitmap codec is not depended on external libraries and is
564       always available.
565
566       BitDepth INT
567           Original bit depth, may differ from "Image::bpp".
568
569           Not valid as a saving parameter.
570
571       Compression STRING
572           Bitmap compressing method.
573
574           Not valid as a saving parameter.
575
576       HotSpotX, HotSpotY INT
577           If loading from cursor file, contains pointer hotspot coordinates
578
579       ImportantColors INT
580           Minimal number of colors needed to display the image
581
582       OS2 BOOL
583           Set when loading OS/2 bitmap
584
585       XResolution, YResolution INT
586           Image resolution in PPM
587
588   X11 codec
589       X11, the X Consortium data file codec may depend on external libraries,
590       but is implement internally if these are not found, and is thus always
591       available.
592
593       hotSpotX, hotSpotY INT
594           Contains pointer hotspot coordinates, if any
595
596   XPM codec
597       extensions HASH
598           Set of xpm-specific extension strings. Cannot be used for saving.
599
600       hintsComment, colorsComment, pixelsComment STRING
601           Contains comments to different sections
602
603       hotSpotX, hotSpotY INT
604           Contains pointer hotspot coordinates
605
606       transparentColors [COLOR]
607           Array or transparent colors. Cannot be used for saving.
608
609   JPEG codec
610       Load parameteres
611
612       exifTransform none|auto|wipe
613           If set to "auto" or "wipe", tries to detect whether there is are
614           any exif tags hinting that the image has to be rotated and/or
615           mirrored. If found, applies the transformation accordingly.
616
617           When set to "wipe", in addition to that, removes the exif tags so
618           that subsequent image save won't result in transformed images with
619           exifs tags still present.
620
621           This parameter requires "loadExtras" flag set, because exif tags
622           are stored in extra JPEG data.
623
624       Load output and save input
625
626       appdata [STRING]
627           Array of raw binary strings found in extra JPEG data.
628
629       comment STRING
630           Any comment text found in file.
631
632       progressive BOOL
633           If set, produces a progressively encoded JPEG file.
634
635           Default: 0
636
637           Only used for saving.
638
639       quality INT
640           JPEG quality, 1-100.
641
642           Default: 75
643
644           Only used for saving.
645
646   PNG codec
647       Load input
648
649       background COLOR
650           When PNG file contains alpha channel, and "alpha" is set to
651           "blend", this color is used to blend the background. If set to
652           "clInvalid", default PNG library background color is used.
653
654           Default: clInvalid
655
656           Not applicable for "Prima::Icon".
657
658       gamma REAL
659           Override gamma value applied to the loaded image
660
661           Default: 0.45455
662
663       screen_gamma REAL
664           Current gamma value for the operating system, if specified.
665
666           Default: 2.2
667
668       Load output and save input
669
670       background COLOR
671           Default PNG library background color
672
673           Default: clInvalid, which means PNG library default
674
675       blendMethod blend|no_blend|unknown
676           Signals whether the new frame to be blended over the existing
677           animation, or replace it.
678
679       delayTime $milliseconds
680           Delay time between frames
681
682       default_frame BOOLEAN
683           When set, means that the first image is a "default" frame, a
684           special backward-compatibility image that is supposed to be
685           excluded from the animation sequence, to be displayed only when all
686           animation frames cannot be loaded for whatever reason.
687
688       disposalMethod none|background|restore|unknown
689           Signals whether the frame, before being replaced, is to be erased
690           by the background color, previous frame, or none.
691
692       gamma REAL
693           Gamma value found in file.
694
695           Default: 0.45455
696
697       hasAlpha BOOLEAN
698           If set, image contains alpha channel
699
700       iccp_name, iccp_profile STRING
701           Embedded ICC color profiles in raw format
702
703           Default: "unspecified" and "".
704
705       interlaced BOOL
706           If set, PNG file is interlaced
707
708           Default: 0
709
710       left INTEGER
711           Frame horizontal offset from the screen
712
713       loopCount INTEGER
714           How many times the animation sequence should run, or 0 for forever.
715
716       mng_datastream BOOL
717           If set, file contains a MNG datastream
718
719           Default: 0
720
721       offset_x, offset_y INT
722           Positive offset from the left edge of the screen to offset_x and
723           the positive offset from the left edge of the screen to offset_y
724
725           Default: 0
726
727       offset_dimension pixel|micrometer
728           Offset units
729
730           Default: pixel
731
732       render_intent none|saturation|perceptual|relative|absolute
733           See PNG docs.
734
735           Default: none
736
737       resolution_x, resolution_y INT
738           Image resolution
739
740           Default: 0
741
742       resolution_dimension meter|unknown
743           Image resolution units
744
745           Default: meter
746
747       scale_x, scale_y
748           Image scale factors
749
750           Default: 1
751
752       scale_unit meter|radian|unknown
753           Image scale factor units
754
755           Default: unknown
756
757       screenWidth, screenHeight INTEGER
758       text HASH
759           Free-text comments found in the file
760
761           Default: "{}"
762
763       top INTEGER
764           Frame vertical offset from the screen
765
766       transparency_table [INT]
767           When a paletted image contains transparent colors, returns array of
768           palette indexes ("transparency_table") in 0-255 range, where each
769           number is an alpha value.
770
771           Default value: empty array
772
773       transparent_color COLOR
774           One transparent color value for 24-bit PNG images.
775
776           Default value: clInvalid (i.e. none)
777
778       transparent_color_index INT
779           One transparent color value, as palette index for 8- or less- bit
780           PNG images.
781
782           Default value: -1 (i.e. none)
783
784           Not applicable for load.
785
786   TIFF codec
787       Load input
788
789       MinIsWhite BOOL
790           Automatically invert "PHOTOMETRIC_MINISWHITE" images
791
792           Default: 1
793
794       Fax BOOL
795           If set, converts 1-bit grayscale with ratio 2:1 into 2-bit
796           grayscale (alglorithm also known as faxpect).
797
798           Default: 0
799
800       Load output
801
802       Photometric STRING
803           TIFF "PHOTOMETRIC_XXX" constant. One of:
804
805             MinIsWhite
806             MinIsBlack
807             Palette
808             YCbCr
809             RGB
810             LogL
811             LogLUV
812             Separated
813             MASK
814             CIELAB
815             DEPTH
816             Unknown
817
818       BitsPerSample INT
819           Bits used to represent a single sample, 1-64
820
821       SamplesPerPixel INT
822           Number of samples per pixel, 1-4. F.ex. most images have 1 sample.
823           Planar TIFFs may split low and high bytes in 2 samples.  RGB has 3
824           samples, YCbCr and RGBA has 4.
825
826       PlanarConfig contiguous|separate
827           "separate" images split individual samples or components (f.ex. R
828           and G and B) into individual planes. "contiguous" mix sample bytes
829           one after another.
830
831       SampleFormat STRING
832           Pixel sample format, one of:
833
834             unsigned integer
835             signed integer
836             floating point
837             untyped data
838             complex signed int
839             complex floating point
840
841       Tiled BOOL
842           If set, TIFF is tiled
843
844       Faxpect BOOL
845           When "Fax" option set set to "true", and indeed the image was
846           converted from 1 to 2 bits, this parameter will be set to signal
847           this.
848
849       CompressionType STRING
850           Compression algorithm used for reading TIFF. One of:
851
852             NONE
853             CCITTRLE
854             CCITTFAX3
855             CCITTFAX4
856             LZW
857             OJPEG
858             JPEG
859             NEXT
860             CCITTRLEW
861             PACKBITS
862             THUNDERSCAN
863             IT8CTPAD
864             IT8LW
865             IT8MP
866             IT8BL
867             PIXARFILM
868             PIXARLOG
869             DEFLATE
870             ADOBE_DEFLATE
871             DCS
872             JBIG
873             SGILOG
874             SGILOG24
875
876       Save input
877
878       Compression STRING
879           Same values as in "CompressionType". Different names are used to
880           avoid implicit but impossible compression selection, because
881           tibtiff can decompress many types, but compress only a few.
882
883       Load output and save input
884
885       generic strings
886           The following keys have no specific meanings for Prima, but are
887           both recognized for loading and saving:
888
889             Artist
890             Copyright
891             DateTime
892             DocumentName
893             HostComputer
894             ImageDescription
895             Make
896             Model
897             PageName
898             PageNumber
899             PageNumber2
900
901       PageNumber, PageNumber2 INT
902           Default: 1
903
904       ResolutionUnit inch|centimeter|none
905           Default: none
906
907       Software
908           Default: Prima
909
910       XPosition, YPosition INT
911           Default: 0
912
913       XResolution, YResolution INT
914           Default: 1200
915
916   GIF codec
917       For GIF animation see Prima::Image::Animate.
918
919       The following load output and save input keys are recognized:
920
921       comment STRING
922           GIF comment text
923
924       delayTime INT
925           Delay in hundredth of a second between frames
926
927           Default: 1
928
929       disposalMethod INT
930           Animation frame disposal method
931
932             DISPOSE_NOT_SPECIFIED    = 0; # Leave frame, let new frame draw on top
933             DISPOSE_KEEP             = 1; # Leave frame, let new frame draw on top
934             DISPOSE_CLEAR            = 2; # Clear the frame's area, revealing bg
935             DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame
936
937           Default: 0
938
939       interlaced BOOL
940           If set, GIF is interlaced
941
942           Default: 0
943
944       left, top INT
945           Frame offset in pixels
946
947           Default: 0
948
949       loopCount INT
950           How many times the GIF animation loops. 0 means indefinite.
951
952           Default: 1
953
954       screenBackGroundColor COLOR
955           GIF screen background color
956
957           Default: 0
958
959       screenColorResolution INT
960           Default: 256
961
962       screenWidth, screenHeight INT
963           Default: -1, i.e. use image width and height
964
965       screenPalette [INT]
966           Default: 0,0,0,255,255,255
967
968       transparentColorIndex INT
969           Index of GIF transparent color
970
971           Default: 0
972
973       userInput INT
974           User input flag
975
976           Default: 0
977
978   WebP codec
979       Load input
980
981       background $ARGB_color
982           Integer constant encoded as ARGB, hints the background to be used
983
984       blendMethod blend|no_blend|unknown
985           Signals whether the new frame to be blended over the existing
986           animation, or replace it.
987
988       delayTime $milliseconds
989           Delay time between frames
990
991       disposalMethod none|background|unknown
992           Signals whether the frame, before being replaced, is to be erased
993           by the background color or not.
994
995       hasAlpha BOOLEAN
996           If set, image contains alpha channel
997
998       left INTEGER
999           Frame horizontal offset from the screen
1000
1001       loopCount INTEGER
1002           How many times the animation sequence should run, or 0 for forever.
1003
1004       screenWidth INTEGER
1005       screenHeight INTEGER
1006       top INTEGER
1007           Frame vertical offset from the screen
1008
1009       Save input
1010
1011       WebP requires all images to have same dimensions.  Also, saving the
1012       webp loading result might fail because loaded frames might only
1013       contains parts to be superimposed on each other, while saving requires
1014       always full frames. To convert webp loaded frames to something that can
1015       be saved later more-or-less identically, use
1016       "Prima::Image::webp::animation_to_frames" converter:
1017
1018          use Prima qw(Image::webp);
1019          my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@;
1020          @i = Prima::Image::webp::animation_to_frames(@i);
1021          die $@ if @i != Prima::Icon->save('target.webp', images => \@i);
1022
1023       background $ARGB_color
1024           Integer constant encoded as ARGB, hints the background to be used
1025
1026       compression lossless (default)|lossy|mixed
1027       delay $milliseconds
1028       filter_strength INTEGER
1029           Setting between 0 and 100, 0 means off.
1030
1031       kmax INTEGER
1032           Min distance between key frames. Default is 9 for lossless
1033           compression, and 3 for lossy
1034
1035       kmin INTEGER
1036           Max distance between key frames. Default is 17 for lossless
1037           compression, and 5 for lossy
1038
1039       loopCount 0
1040           How many times the animation sequence should run, or 0 for forever.
1041
1042       method INTEGER
1043           Compression method vs size, 0 (fast) to 6 (slow)
1044
1045       minimize_size BOOLEAN
1046           Minimize output size (off by default)
1047
1048       quality INTEGER
1049           Quality factor (0:small..100:big)
1050
1051       thread_level BOOLEAN
1052           Use multi-threading if available (off by default)
1053

AUTHOR

1055       Dmitry Karasik, <dmitry@karasik.eu.org>.
1056

SEE ALSO

1058       Prima, Prima::Image, Prima::codecs
1059
1060
1061
1062perl v5.34.0                      2021-07-22         pod::Prima::image-load(3)
Impressum