1pod::Prima::image-load(U3s)er Contributed Perl Documentatpioodn::Prima::image-load(3)
2
6 Prima::image-load - Using image subsystem
7
9 Details on image subsystem - image loading, saving, and codec
10 managements
11
13 Simple loading
14 Simplest case, loading a single image would look like:
15 my $x = Prima::Image-> load( 'filename.duf');
17 die "$@" unless $x;
18 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 my $x = Prima::Image-> create;
24 die "$@" unless $x-> load( 'filename.duf');
25 In both cases $x contains image data upon success. Error is returned
27 into $@ variable ( see perldoc perlvar for more info).
28 Loading from stream
30 "Prima::Image" can also load image by reading from a stream:
31 open FILE, 'a.jpeg' or die "Cannot open:$!";
33 binmode FILE;
34 my $x = Prima::Image-> load( \*FILE);
35 die "$@" unless $x;
36 Multiframe loading
38 Multiframe load call can be also issued in two ways:
39 my @x = Prima::Image-> load( 'filename.duf', loadAll => 1);
41 die "$@" unless $x[-1];
42 my $x = Prima::Image-> create;
44 my @x = $x-> load( 'filename.duf', loadAll => 1);
45 die "$@" unless $x[-1];
46 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 Multiframe syntax is expressed in a set of extra hash keys. These keys
54 are:
55 loadAll
57 Request for loading all frames that can be read from a file.
58 Example:
59 loadAll => 1
61 index
63 If present, returns a single frame with index given. Example:
64 index => 8
66 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 map => [0, 10, 15..20]
72 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 my $x = Prima::Image-> load( $f, loadExtras => 1);
80 die "$@" unless $x;
81 for ( keys %{$x-> {extras}}) {
82 print " $_ : $x->{extras}->{$_}\n";
83 }
84 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 codecID : 1
90 transparentColorIndex : 1
91 comment : created by GIMP
92 frames : 18
93 '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 '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 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 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 $x-> load( $f, loadAll => 1, profiles => [
125 {loadExtras => 0},
126 {loadExtras => 1},
127 ]);
128 First hash there applies to frame index 0, second - to frame index 1.
130 Note that in code
131 $x-> load( $f,
133 map => [ 5, 10],
134 profiles => [
135 {loadExtras => 0},
136 {loadExtras => 1},
137 ]);
138 first hash applies to frame index 5, and second - to frame index 10.
140 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 $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 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 $x-> load( $f, map => [], loadExtras => 1);
157 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 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 my @x = Prima::Image-> load( $f,
168 map => [ 1..3],
169 className => 'Prima::Icon',
170 profiles => [
171 {},
172 { className => 'Prima::Image' },
173 {}
174 ],
175 In this example @x will be ( Icon, Image, Icon) upon success.
177 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 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 onHeaderReady $OBJECT
199 onDataReady $OBJECT, $X, $Y, $WIDTH, $HEIGHT
200 "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 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 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 $i = Prima::Image-> new(
220 onDataReady => sub {
221 $progress_widget-> put_image( 0, 0, $i);
222 },
223 );
224 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 $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 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 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
256 Simple saving
257 Typical saving code will be:
258 die "$@" unless $x-> save( 'filename.duf');
260 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 die "$@" unless Prima::Image-> save( 'filename.duf',
265 images => [ $x]);
266 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 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 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 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 die "$@" if scalar(@images) > Prima::Image-> save( $f,
289 images => \@images);
290 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 $x-> {extras}-> {comments} = 'Created by Prima';
299 $x-> save( $f);
300 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 $x-> {extras}-> {codecID} = 1;
310 $x-> save( $f);
311 Actual correspondence between codecs and their indices is described
313 latter.
314 NB - if codecID is not given, codec is selected by the file extension.
316 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 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 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
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 Codec information that is contained in these hashes is divided into
347 following parameters:
348 codecID
350 Unique integer value for a codec, same as index of the codec entry
351 in results of "Prima::Image->codecs";
352 name
354 codec full name, string
355 vendor
357 codec vendor, string
358 versionMajor and versionMinor
360 usually underlying library versions, integers
361 fileExtensions
363 array of strings, with file extensions that are typical to a codec.
364 example: ['tif', 'tiff']
365 fileType
367 Description of a type of a file, that codec is designed to work
368 with. String.
369 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 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 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 canLoad
390 1 if a codec can load images, 0 if not
391 canLoadStream
393 1 if a codec can load images from streams, 0 otherwise
394 canLoadMultiple
396 1 if a codec can handle multiframe load requests and load frames
397 with index more than zero. 0 if not.
398 canSave
400 1 if a codec can save images, 0 if not.
401 canSaveStream
403 1 if a codec can save images to streams, 0 otherwise
404 canSaveMultiple
406 Set if a codec can save more that one frame
407 canAppend
409 Set if a codec can append frames to an exising file
410 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 loadInput
418 Hash, where keys are those that are accepted by Prima::Image->
419 load, and values are default values for these keys.
420 loadOutput
422 Array of strings, each of those is a name of extra information
423 entry in 'extras' hash.
424 saveInput
426 Hash, where keys are those that are accepted by Prima::Image->
427 save, and values are default values for these keys.
428 mime
430 array of strings, with file extensions that are typical to a codec.
431 example: ['image/xbm', 'image/x-bitmap']
432
434 This section describes parameters accepted and data returned by
435 "Prima::Image::load"
436 Common
438 Loading parameters
439 blending BOOLEAN = 1
441 Affects how to treat alpha channel bits, if any.
442 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 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 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 eventDelay INT
461 Specifies "onDataReady" event granularity in microseconds, if image
462 codec is capable of triggering this event.
463 Default: 100
465 iconUnmask BOOL
467 If set, "Prima::Icon::autoMasking" is set to "am::None" prior to
468 the file loading.
469 Default: false. Only actual for "Prima::Icon" loading.
471 index INT
473 When loading from a multiframe file, selects the frame index to
474 load.
475 Default: 0
477 map [INT]
479 When loading from a multiframe file, selects set of frame indexes
480 to load.
481 Default: undef
483 loadExtras BOOL
485 If set, all available extra information will be stored in
486 "{extras}" hash on the loaded object.
487 Default: false
489 loadAll BOOL
491 When loading from a multiframe file, selects that all frames are to
492 be loaded
493 Default: false
495 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 Default: false
502 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 Default: false
510 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 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 Default: false
523 See also: frames.
525 Load output
527 codecID INT
529 Indicates the internal codec ID used to load the image. Can be used
530 for "Image::save".
531 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 height INT
538 When "noImageData" is in action, contains image height.
539 truncated BOOL
541 When "noIncomplete" is in action, is set if image was truncated.
542 The value is the error string.
543 width INT
545 When "noImageData" is in action, contains image width.
546 Saving parameters
548 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 Default: true
556 codecID INT
558 Overrides codec selection based on filename extension.
559 Default: undef
561 BMP codec
563 BMP, the bitmap codec is not depended on external libraries and is
564 always available.
565 BitDepth INT
567 Original bit depth, may differ from "Image::bpp".
568 Not valid as a saving parameter.
570 Compression STRING
572 Bitmap compressing method.
573 Not valid as a saving parameter.
575 HotSpotX, HotSpotY INT
577 If loading from cursor file, contains pointer hotspot coordinates
578 ImportantColors INT
580 Minimal number of colors needed to display the image
581 OS2 BOOL
583 Set when loading OS/2 bitmap
584 XResolution, YResolution INT
586 Image resolution in PPM
587 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 hotSpotX, hotSpotY INT
594 Contains pointer hotspot coordinates, if any
595 XPM codec
597 extensions HASH
598 Set of xpm-specific extension strings. Cannot be used for saving.
599 hintsComment, colorsComment, pixelsComment STRING
601 Contains comments to different sections
602 hotSpotX, hotSpotY INT
604 Contains pointer hotspot coordinates
605 transparentColors [COLOR]
607 Array or transparent colors. Cannot be used for saving.
608 JPEG codec
610 Load parameteres
611 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 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 This parameter requires "loadExtras" flag set, because exif tags
622 are stored in extra JPEG data.
623 Load output and save input
625 appdata [STRING]
627 Array of raw binary strings found in extra JPEG data.
628 comment STRING
630 Any comment text found in file.
631 progressive BOOL
633 If set, produces a progressively encoded JPEG file.
634 Default: 0
636 Only used for saving.
638 quality INT
640 JPEG quality, 1-100.
641 Default: 75
643 Only used for saving.
645 PNG codec
647 Load input
648 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 Default: clInvalid
655 Not applicable for "Prima::Icon".
657 gamma REAL
659 Override gamma value applied to the loaded image
660 Default: 0.45455
662 screen_gamma REAL
664 Current gamma value for the operating system, if specified.
665 Default: 2.2
667 Load output and save input
669 background COLOR
671 Default PNG library background color
672 Default: clInvalid, which means PNG library default
674 blendMethod blend|no_blend|unknown
676 Signals whether the new frame to be blended over the existing
677 animation, or replace it.
678 delayTime $milliseconds
680 Delay time between frames
681 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 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 gamma REAL
693 Gamma value found in file.
694 Default: 0.45455
696 hasAlpha BOOLEAN
698 If set, image contains alpha channel
699 iccp_name, iccp_profile STRING
701 Embedded ICC color profiles in raw format
702 Default: "unspecified" and "".
704 interlaced BOOL
706 If set, PNG file is interlaced
707 Default: 0
709 left INTEGER
711 Frame horizontal offset from the screen
712 loopCount INTEGER
714 How many times the animation sequence should run, or 0 for forever.
715 mng_datastream BOOL
717 If set, file contains a MNG datastream
718 Default: 0
720 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 Default: 0
726 offset_dimension pixel|micrometer
728 Offset units
729 Default: pixel
731 render_intent none|saturation|perceptual|relative|absolute
733 See PNG docs.
734 Default: none
736 resolution_x, resolution_y INT
738 Image resolution
739 Default: 0
741 resolution_dimension meter|unknown
743 Image resolution units
744 Default: meter
746 scale_x, scale_y
748 Image scale factors
749 Default: 1
751 scale_unit meter|radian|unknown
753 Image scale factor units
754 Default: unknown
756 screenWidth, screenHeight INTEGER
758 text HASH
759 Free-text comments found in the file
760 Default: "{}"
762 top INTEGER
764 Frame vertical offset from the screen
765 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 Default value: empty array
772 transparent_color COLOR
774 One transparent color value for 24-bit PNG images.
775 Default value: clInvalid (i.e. none)
777 transparent_color_index INT
779 One transparent color value, as palette index for 8- or less- bit
780 PNG images.
781 Default value: -1 (i.e. none)
783 Not applicable for load.
785 TIFF codec
787 Load input
788 MinIsWhite BOOL
790 Automatically invert "PHOTOMETRIC_MINISWHITE" images
791 Default: 1
793 Fax BOOL
795 If set, converts 1-bit grayscale with ratio 2:1 into 2-bit
796 grayscale (alglorithm also known as faxpect).
797 Default: 0
799 Load output
801 Photometric STRING
803 TIFF "PHOTOMETRIC_XXX" constant. One of:
804 MinIsWhite
806 MinIsBlack
807 Palette
808 YCbCr
809 RGB
810 LogL
811 LogLUV
812 Separated
813 MASK
814 CIELAB
815 DEPTH
816 Unknown
817 BitsPerSample INT
819 Bits used to represent a single sample, 1-64
820 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 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 SampleFormat STRING
832 Pixel sample format, one of:
833 unsigned integer
835 signed integer
836 floating point
837 untyped data
838 complex signed int
839 complex floating point
840 Tiled BOOL
842 If set, TIFF is tiled
843 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 CompressionType STRING
850 Compression algorithm used for reading TIFF. One of:
851 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 Save input
877 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 Load output and save input
884 generic strings
886 The following keys have no specific meanings for Prima, but are
887 both recognized for loading and saving:
888 Artist
890 Copyright
891 DateTime
892 DocumentName
893 HostComputer
894 ImageDescription
895 Make
896 Model
897 PageName
898 PageNumber
899 PageNumber2
900 PageNumber, PageNumber2 INT
902 Default: 1
903 ResolutionUnit inch|centimeter|none
905 Default: none
906 Software
908 Default: Prima
909 XPosition, YPosition INT
911 Default: 0
912 XResolution, YResolution INT
914 Default: 1200
915 GIF codec
917 For GIF animation see Prima::Image::Animate.
918 The following load output and save input keys are recognized:
920 comment STRING
922 GIF comment text
923 delayTime INT
925 Delay in hundredth of a second between frames
926 Default: 1
928 disposalMethod INT
930 Animation frame disposal method
931 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 Default: 0
938 interlaced BOOL
940 If set, GIF is interlaced
941 Default: 0
943 left, top INT
945 Frame offset in pixels
946 Default: 0
948 loopCount INT
950 How many times the GIF animation loops. 0 means indefinite.
951 Default: 1
953 screenBackGroundColor COLOR
955 GIF screen background color
956 Default: 0
958 screenColorResolution INT
960 Default: 256
961 screenWidth, screenHeight INT
963 Default: -1, i.e. use image width and height
964 screenPalette [INT]
966 Default: 0,0,0,255,255,255
967 transparentColorIndex INT
969 Index of GIF transparent color
970 Default: 0
972 userInput INT
974 User input flag
975 Default: 0
977 WebP codec
979 Load input
980 background $ARGB_color
982 Integer constant encoded as ARGB, hints the background to be used
983 blendMethod blend|no_blend|unknown
985 Signals whether the new frame to be blended over the existing
986 animation, or replace it.
987 delayTime $milliseconds
989 Delay time between frames
990 disposalMethod none|background|unknown
992 Signals whether the frame, before being replaced, is to be erased
993 by the background color or not.
994 hasAlpha BOOLEAN
996 If set, image contains alpha channel
997 left INTEGER
999 Frame horizontal offset from the screen
1000 loopCount INTEGER
1002 How many times the animation sequence should run, or 0 for forever.
1003 screenWidth INTEGER
1005 screenHeight INTEGER
1006 top INTEGER
1007 Frame vertical offset from the screen
1008 Save input
1010 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 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 background $ARGB_color
1024 Integer constant encoded as ARGB, hints the background to be used
1025 compression lossless (default)|lossy|mixed
1027 delay $milliseconds
1028 filter_strength INTEGER
1029 Setting between 0 and 100, 0 means off.
1030 kmax INTEGER
1032 Min distance between key frames. Default is 9 for lossless
1033 compression, and 3 for lossy
1034 kmin INTEGER
1036 Max distance between key frames. Default is 17 for lossless
1037 compression, and 5 for lossy
1038 loopCount 0
1040 How many times the animation sequence should run, or 0 for forever.
1041 method INTEGER
1043 Compression method vs size, 0 (fast) to 6 (slow)
1044 minimize_size BOOLEAN
1046 Minimize output size (off by default)
1047 quality INTEGER
1049 Quality factor (0:small..100:big)
1050 thread_level BOOLEAN
1052 Use multi-threading if available (off by default)
1053
1055 Dmitry Karasik, <dmitry@karasik.eu.org>.
1056
1058 Prima, Prima::Image, Prima::codecs
1059perl v5.36.0 2022-07-22 pod::Prima::image-load(3)