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::ImageDialog::SaveImageDialog code might be useful.
327
328       When the conversion takes place, Image property 'conversion' is used
329       for selection of an error distribution algorithm, if down-sampling is
330       required.
331
332   Appending frames to an existing file
333       This functionality is under design, but the common outlines are already
334       set.  Profile key 'append' ( 0 by default ) triggers this behavior - if
335       it is set, then an append attempt is made.
336

Managing codecs

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

API

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

AUTHOR

1050       Dmitry Karasik, <dmitry@karasik.eu.org>.
1051

SEE ALSO

1053       Prima, Prima::Image, Prima::codecs
1054
1055
1056
1057perl v5.30.1                      2020-01-30         pod::Prima::image-load(3)
Impressum