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