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
255   Inline files
256       Using "Prima::Image::base64" it is possible to convert images into an
257       base64 format, and embed the result directly into the source. Assuming
258       an appropriate codec was compiled, the following would work:
259
260               my $icon = Prima::Icon->load_stream(<<~'ICON');
261                       R0lGODdhIAAgAIAAAAAAAP///ywAAAAAIAAgAIAAAAD///8CT4SPqcvtD6OctNqLcwogcK91nEhq
262                       3gim2Umm4+W2IBzX0fvl8jTr9SeZiU5E4a1XLHZ4yaal6XwFoSwMVUVzhoZSaQW6ZXjD5LL5jE6r
263                       DQUAOw==
264                       ICON
265
266               print $icon->save_stream;
267

Saving

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

Managing codecs

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

API

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

AUTHOR

1115       Dmitry Karasik, <dmitry@karasik.eu.org>.
1116

SEE ALSO

1118       Prima, Prima::Image, Prima::codecs
1119
1120
1121
1122perl v5.36.0                      2023-03-20         pod::Prima::image-load(3)
Impressum