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::ImageDialog::SaveImageDialog code might be useful.
327 When the conversion takes place, Image property 'conversion' is used
329 for selection of an error distribution algorithm, if down-sampling is
330 required.
331 Appending frames to an existing file
333 This functionality is under design, but the common outlines are already
334 set. Profile key 'append' ( 0 by default ) triggers this behavior - if
335 it is set, then an append attempt is made.
336
338 Prima provides single function, Prima::Image-> codecs, which returns an
339 anonymous array of hashes, where every hash entry corresponds to a
340 registered codec. 'codecID' parameter on load and save requests is
341 actually an index in this array. Indexes for a codecs registered once
342 never change, so it is safe to manipulate these numbers within single
343 program run.
344 Codec information that is contained in these hashes is divided into
346 following parameters:
347 codecID
349 Unique integer value for a codec, same as index of the codec entry
350 in results of "Prima::Image->codecs";
351 name
353 codec full name, string
354 vendor
356 codec vendor, string
357 versionMajor and versionMinor
359 usually underlying library versions, integers
360 fileExtensions
362 array of strings, with file extensions that are typical to a codec.
363 example: ['tif', 'tiff']
364 fileType
366 Description of a type of a file, that codec is designed to work
367 with. String.
368 fileShortType
370 Short description of a type of a file, that codec is designed to
371 work with. ( short means 3-4 characters ). String.
372 featuresSupported
374 Array of strings, with some features description that a codec
375 supports - usually codecs implement only a part of file format
376 specification, so it is always interesting to know, what part it
377 is.
378 module and package
380 Specify a perl module, usually inside Prima/Image directory into
381 Prima distribution, and a package inside the module. The package
382 contains some specific functions for work with codec-specific
383 parameters. Current implementation defines only ::save_dialog()
384 function, that returns a dialog that allows to change these
385 parameters. See Prima::ImageDialog::SaveImageDialog for details.
386 Strings, undefined if empty.
387 canLoad
389 1 if a codec can load images, 0 if not
390 canLoadStream
392 1 if a codec can load images from streams, 0 otherwise
393 canLoadMultiple
395 1 if a codec can handle multiframe load requests and load frames
396 with index more than zero. 0 if not.
397 canSave
399 1 if a codec can save images, 0 if not.
400 canSaveStream
402 1 if a codec can save images to streams, 0 otherwise
403 canSaveMultiple
405 Set if a codec can save more that one frame
406 canAppend
408 Set if a codec can append frames to an exising file
409 types
411 Array of integers - each is a combination of im:: flags, an image
412 type, which a codec is capable of saving. First type in list is a
413 default one; if image type that to be saved is not in that list,
414 the image will be converted to this default type.
415 loadInput
417 Hash, where keys are those that are accepted by Prima::Image->
418 load, and values are default values for these keys.
419 loadOutput
421 Array of strings, each of those is a name of extra information
422 entry in 'extras' hash.
423 saveInput
425 Hash, where keys are those that are accepted by Prima::Image->
426 save, and values are default values for these keys.
427
429 This section describes parameters accepted and data returned by
430 "Prima::Image::load"
431 Common
433 Loading parameters
434 blending BOOLEAN = 1
436 Affects how to treat alpha channel bits, if any.
437 If set, mixes the alpha channel with background color in case if
439 loading to an image, or premultiplies color bits (either data or
440 palette) with alpha, if loading to icon. Note that saving back the
441 object will result in different image, but the object is ready to
442 be displayed immediately.
443 If unset, color and eventual alpha bits, if loaded to an icon, will
445 not be affected in any way. Note that saving back the object will
446 result in the same image, but the object is not ready to be
447 displayed immediately. See also: "premultiply_alpha" in
448 Prima::Image.
449 className STRING
451 When loading more than one image, this string is used to create
452 instances of image containers. By default the calling class is used
453 (i.e. "Prima::Image" or "Prima::Icon").
454 eventDelay INT
456 Specifies "onDataReady" event granularity in microseconds, if image
457 codec is capable of triggering this event.
458 Default: 100
460 iconUnmask BOOL
462 If set, "Prima::Icon::autoMasking" is set to "am::None" prior to
463 the file loading.
464 Default: false. Only actual for "Prima::Icon" loading.
466 index INT
468 When loading from a multiframe file, selects the frame index to
469 load.
470 Default: 0
472 map [INT]
474 When loading from a multiframe file, selects set of frame indexes
475 to load.
476 Default: undef
478 loadExtras BOOL
480 If set, all available extra information will be stored in
481 "{extras}" hash on the loaded object.
482 Default: false
484 loadAll BOOL
486 When loading from a multiframe file, selects that all frames are to
487 be loaded
488 Default: false
490 noImageData BOOL
492 When set, neither image data is not loaded, nor image dimensions
493 are changed (newly created images have size of 1x1). Instead,
494 "{extras}" contains "width" and "height" integers.
495 Default: false
497 noIncomplete BOOL
499 Affects the action when image is incomplete, truncated, etc. If
500 set, signals an error. Otherwise no error is signalled and whatever
501 data could be recovered from the image are returned, and
502 "truncated" flag is set.
503 Default: false
505 profiles [HASH]
507 Array of hashes passed down to each frame in multiframe loads. Each
508 frame load request will be passed an individual hash, a result of
509 hash join of all profiles passed to "Image::load" and the nth hash
510 in the array.
511 wantFrames BOOL
513 Affects how the number of frames in a file is reported in "frames"
514 flag. If set, always scans the file for exact number. Otherwise it
515 is up to the codec to do that.
516 Default: false
518 See also: frames.
520 Load output
522 codecID INT
524 Indicates the internal codec ID used to load the image. Can be used
525 for "Image::save".
526 frames INT
528 If set to a positive integer, indicates number of frames in a file.
529 Otherwise signals that there are frames, but codec needs an
530 expensive scan to calculate the frames (and "wantFrames" set).
531 height INT
533 When "noImageData" is in action, contains image height.
534 truncated BOOL
536 When "noIncomplete" is in action, is set if image was truncated.
537 The value is the error string.
538 width INT
540 When "noImageData" is in action, contains image width.
541 Saving parameters
543 autoConvert BOOL
545 Affects the action when image cannot be stored in file format in
546 its existing pixel format. If set, the system tries to convert
547 image into a pixel format understood by the selected codec. Fails
548 otherwise.
549 Default: true
551 codecID INT
553 Overrides codec selection based on filename extension.
554 Default: undef
556 BMP codec
558 BMP, the bitmap codec is not depended on external libraries and is
559 always available.
560 BitDepth INT
562 Original bit depth, may differ from "Image::bpp".
563 Not valid as a saving parameter.
565 Compression STRING
567 Bitmap compressing method.
568 Not valid as a saving parameter.
570 HotSpotX, HotSpotY INT
572 If loading from cursor file, contains pointer hotspot coordinates
573 ImportantColors INT
575 Minimal number of colors needed to display the image
576 OS2 BOOL
578 Set when loading OS/2 bitmap
579 XResolution, YResolution INT
581 Image resolution in PPM
582 X11 codec
584 X11, the X Consortium data file codec may depend on external libraries,
585 but is implement internally if these are not found, and is thus always
586 available.
587 hotSpotX, hotSpotY INT
589 Contains pointer hotspot coordinates, if any
590 XPM codec
592 extensions HASH
593 Set of xpm-specific extension strings. Cannot be used for saving.
594 hintsComment, colorsComment, pixelsComment STRING
596 Contains comments to different sections
597 hotSpotX, hotSpotY INT
599 Contains pointer hotspot coordinates
600 transparentColors [COLOR]
602 Array or transparent colors. Cannot be used for saving.
603 JPEG codec
605 Load parameteres
606 exifTransform none|auto|wipe
608 If set to "auto" or "wipe", tries to detect whether there is are
609 any exif tags hinting that the image has to be rotated and/or
610 mirrored. If found, applies the transformation accordingly.
611 When set to "wipe", in addition to that, removes the exif tags so
613 that subsequent image save won't result in transformed images with
614 exifs tags still present.
615 This parameter requires "loadExtras" flag set, because exif tags
617 are stored in extra JPEG data.
618 Load output and save input
620 appdata [STRING]
622 Array of raw binary strings found in extra JPEG data.
623 comment STRING
625 Any comment text found in file.
626 progressive BOOL
628 If set, produces a progressively encoded JPEG file.
629 Default: 0
631 Only used for saving.
633 quality INT
635 JPEG quality, 1-100.
636 Default: 75
638 Only used for saving.
640 PNG codec
642 Load input
643 background COLOR
645 When PNG file contains alpha channel, and "alpha" is set to
646 "blend", this color is used to blend the background. If set to
647 "clInvalid", default PNG library background color is used.
648 Default: clInvalid
650 Not applicable "Prima::Icon".
652 blending BOOLEAN = 1
654 Affects how to treat alpha channel bits, if any.
655 If set, mixes the alpha channel with "background" color in case if
657 loading to an image, or premultiplies color bits (either data or
658 palette) with alpha, if loading to icon. Note that saving back the
659 object will result in different image, but the object is ready to
660 be displayed immediately.
661 If unset, color and eventual alpha bits, if loaded to an icon, will
663 not be affected in any way. Note that saving back the object will
664 result in the same image, but the object is not ready to be
665 displayed immediately. See also: "premultiply_alpha" in
666 Prima::Image.
667 gamma REAL
669 Override gamma value applied to the loaded image
670 Default: 0.45455
672 screen_gamma REAL
674 Current gamma value for the operating system, if specified.
675 Default: 2.2
677 Load output and save input
679 background COLOR
681 Default PNG library background color
682 Default: clInvalid, which means PNG library default
684 gamma REAL
686 Gamma value found in file.
687 Default: 0.45455
689 iccp_name, iccp_profile STRING
691 Embedded ICC color profiles in raw format
692 Default: "unspecified" and "".
694 interlaced BOOL
696 If set, PNG file is interlaced
697 Default: 0
699 mng_datastream BOOL
701 If set, file contains a MNG datastream
702 Default: 0
704 offset_x, offset_y INT
706 Positive offset from the left edge of the screen to offset_x and
707 the positive offset from the left edge of the screen to offset_y
708 Default: 0
710 offset_dimension pixel|micrometer
712 Offset units
713 Default: pixel
715 render_intent none|saturation|perceptual|relative|absolute
717 See PNG docs.
718 Default: none
720 resolution_x, resolution_y INT
722 Image resolution
723 Default: 0
725 resolution_dimension meter|unknown
727 Image resolution units
728 Default: meter
730 scale_x, scale_y
732 Image scale factors
733 Default: 1
735 scale_unit meter|radian|unknown
737 Image scale factor units
738 Default: unknown
740 text HASH
742 Free-text comments found in the file
743 Default: "{}"
745 transparent_colors [COLOR], transparency_table [INT]
747 When image contains transparent colors, returns either array of
748 palette indexes ("transparency_table") in 0-255 range, for paletted
749 images. Or an array of colors in RGB form for 24-bit images
750 ("transparent_colors").
751 Not applicable for save.
753 Note: support for transparency is not symmetric; codec cannot
755 automatically save the transparency info read from PNG files. See
756 "transparent_color" and "transparent_color_index" for manual save
757 of one transparent color.
758 transparent_color COLOR
760 One transparent color value for 24-bit PNG images.
761 Default value: clInvalid (i.e. none)
763 Not applicable for load.
765 transparent_color_index INT
767 One transparent color value, as palette index for 8- or less- bit
768 PNG images.
769 Default value: -1 (i.e. none)
771 Not applicable for load.
773 TIFF codec
775 Load input
776 MinIsWhite BOOL
778 Automatically invert "PHOTOMETRIC_MINISWHITE" images
779 Default: 1
781 Fax BOOL
783 If set, converts 1-bit grayscale with ratio 2:1 into 2-bit
784 grayscale (alglorithm also known as faxpect).
785 Default: 0
787 Load output
789 Photometric STRING
791 TIFF "PHOTOMETRIC_XXX" constant. One of:
792 MinIsWhite
794 MinIsBlack
795 Palette
796 YCbCr
797 RGB
798 LogL
799 LogLUV
800 Separated
801 MASK
802 CIELAB
803 DEPTH
804 Unknown
805 BitsPerSample INT
807 Bits used to represent a single sample, 1-64
808 SamplesPerPixel INT
810 Number of samples per pixel, 1-4. F.ex. most images have 1 sample.
811 Planar TIFFs may split low and high bytes in 2 samples. RGB has 3
812 samples, YCbCr and RGBA has 4.
813 PlanarConfig contiguous|separate
815 "separate" images split individual samples or components (f.ex. R
816 and G and B) into individual planes. "contiguous" mix sample bytes
817 one after another.
818 SampleFormat STRING
820 Pixel sample format, one of:
821 unsigned integer
823 signed integer
824 floating point
825 untyped data
826 complex signed int
827 complex floating point
828 Tiled BOOL
830 If set, TIFF is tiled
831 Faxpect BOOL
833 When "Fax" option set set to "true", and indeed the image was
834 converted from 1 to 2 bits, this parameter will be set to signal
835 this.
836 CompressionType STRING
838 Compression algorithm used for reading TIFF. One of:
839 NONE
841 CCITTRLE
842 CCITTFAX3
843 CCITTFAX4
844 LZW
845 OJPEG
846 JPEG
847 NEXT
848 CCITTRLEW
849 PACKBITS
850 THUNDERSCAN
851 IT8CTPAD
852 IT8LW
853 IT8MP
854 IT8BL
855 PIXARFILM
856 PIXARLOG
857 DEFLATE
858 ADOBE_DEFLATE
859 DCS
860 JBIG
861 SGILOG
862 SGILOG24
863 Save input
865 Compression STRING
867 Same values as in "CompressionType". Different names are used to
868 avoid implicit but impossible compression selection, because
869 tibtiff can decompress many types, but compress only a few.
870 Load output and save input
872 generic strings
874 The following keys have no specific meanings for Prima, but are
875 both recognized for loading and saving:
876 Artist
878 Copyright
879 DateTime
880 DocumentName
881 HostComputer
882 ImageDescription
883 Make
884 Model
885 PageName
886 PageNumber
887 PageNumber2
888 PageNumber, PageNumber2 INT
890 Default: 1
891 ResolutionUnit inch|centimeter|none
893 Default: none
894 Software
896 Default: Prima
897 XPosition, YPosition INT
899 Default: 0
900 XResolution, YResolution INT
902 Default: 1200
903 GIF codec
905 For GIF animation see Prima::Image::Animate.
906 The following load output and save input keys are recognized:
908 comment STRING
910 GIF comment text
911 delayTime INT
913 Delay in hundredth of a second between frames
914 Default: 1
916 disposalMethod INT
918 Animation frame disposal method
919 DISPOSE_NOT_SPECIFIED = 0; # Leave frame, let new frame draw on top
921 DISPOSE_KEEP = 1; # Leave frame, let new frame draw on top
922 DISPOSE_CLEAR = 2; # Clear the frame's area, revealing bg
923 DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame
924 Default: 0
926 interlaced BOOL
928 If set, GIF is interlaced
929 Default: 0
931 left, top INT
933 Frame offset in pixels
934 Default: 0
936 loopCount INT
938 How many times the GIF animation loops. 0 means indefinite.
939 Default: 1
941 screenBackGroundColor COLOR
943 GIF screen background color
944 Default: 0
946 screenColorResolution INT
948 Default: 256
949 screenWidth, screenHeight INT
951 Default: -1, i.e. use image width and height
952 screenPalette [INT]
954 Default: 0,0,0,255,255,255
955 transparentColorIndex INT
957 Index of GIF transparent color
958 Default: 0
960 userInput INT
962 User input flag
963 Default: 0
965 WebP codec
967 Load input
968 background $ARGB_color
970 Integer constant encoded as ARGB, hints the background to be used
971 blendMethod blend|no_blend|unknown
973 Signals whether the new frame to be blended over the existing
974 animation, or replace it.
975 delayTime $milliseconds
977 Delay time between frames
978 disposalMethod none|background|unknown
980 Signals whether the frame, before being replaced, is to be erased
981 by the background color or not.
982 hasAlpha BOOLEAN
984 If set, image contains alpha channel
985 left INTEGER
987 Frame horizontal offset from the screen
988 loopCount INTEGER
990 How many times the animation sequence should run, or 0 for forever.
991 screenWidth INTEGER
993 screenHeight INTEGER
994 top INTEGER
995 Frame vertical offset from the screen
996 Save input
998 WebP requires all images to have same dimensions. Also, saving the
1000 webp loading result might fail because loaded frames might only
1001 contains parts to be superimposed on each other, while saving requires
1002 always full frames. To convert webp loaded frames to something that can
1003 be saved later more-or-less identically, use
1004 "Prima::Image::webp::animation_to_frames" converter:
1005 use Prima qw(Image::webp);
1007 my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@;
1008 @i = Prima::Image::webp::animation_to_frames(@i);
1009 die $@ if @i != Prima::Icon->save('target.webp', images => \@i);
1010 background $ARGB_color
1012 Integer constant encoded as ARGB, hints the background to be used
1013 compression lossless (default)|lossy|mixed
1015 delay $milliseconds
1016 filter_strength INTEGER
1017 Setting between 0 and 100, 0 means off.
1018 kmax INTEGER
1020 Min distance between key frames. Default is 9 for lossless
1021 compression, and 3 for lossy
1022 kmin INTEGER
1024 Max distance between key frames. Default is 17 for lossless
1025 compression, and 5 for lossy
1026 loopCount 0
1028 How many times the animation sequence should run, or 0 for forever.
1029 method INTEGER
1031 Compression method vs size, 0 (fast) to 6 (slow)
1032 minimize_size BOOLEAN
1034 Minimize output size (off by default)
1035 quality INTEGER
1037 Quality factor (0:small..100:big)
1038 thread_level BOOLEAN
1040 Use multi-threading if available (off by default)
1041
1043 Dmitry Karasik, <dmitry@karasik.eu.org>.
1044
1046 Prima, Prima::Image, Prima::codecs
1047perl v5.30.0 2019-08-21 pod::Prima::image-load(3)