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 Inline files
256 Using "Prima::Image::base64" it is possible to convert images into an
257 base64 format, and embed the result directly into the source. Assuming
258 an appropriate codec was compiled, the following would work:
259 my $icon = Prima::Icon->load_stream(<<~'ICON');
261 R0lGODdhIAAgAIAAAAAAAP///ywAAAAAIAAgAIAAAAD///8CT4SPqcvtD6OctNqLcwogcK91nEhq
262 3gim2Umm4+W2IBzX0fvl8jTr9SeZiU5E4a1XLHZ4yaal6XwFoSwMVUVzhoZSaQW6ZXjD5LL5jE6r
263 DQUAOw==
264 ICON
265 print $icon->save_stream;
267
269 Simple saving
270 Typical saving code will be:
271 die "$@" unless $x-> save( 'filename.duf');
273 Upon a single-frame invocation save returns 1 upon success an 0 on
275 failure. Save requests also can be performed with package syntax:
276 die "$@" unless Prima::Image-> save( 'filename.duf',
278 images => [ $x]);
279 Saving to a stream
281 Saving to a stream requires explicit "codecID" to be supplied. When an
282 image is loaded with "loadExtras", this field is always present on the
283 image object, and is an integer that selects image encoding format.
284 my @png_id =
286 map { $_-> {codecID} }
287 grep { $_-> {fileShortType} =~ /^png$/i }
288 @{ Prima::Image-> codecs };
289 die "No png codec installed" unless @png_id;
290 open FILE, "> a.png" or die "Cannot save:$!";
292 binmode FILE;
293 $image-> save( \*FILE, codecID => $png_id[0])
294 or die "Cannot save:$@";
295 Multiframe saving
297 In multiframe invocation save returns number of successfully saved
298 frames. File is erased though, if error occurred, even after some
299 successfully written frames.
300 die "$@" if scalar(@images) > Prima::Image-> save( $f,
302 images => \@images);
303 Saving extras information
305 All information, that is found in object hash reference 'extras', is
306 assumed to be saved as an extra information. It is a codec's own
307 business how it reacts on invalid and/or unacceptable information - but
308 typical behavior is that keys that were not recognized by the codec
309 just get ignored, and invalid values raise an error.
310 $x-> {extras}-> {comments} = 'Created by Prima';
312 $x-> save( $f);
313 Selecting a codec
315 Extras field 'codecID', the same one that is defined after load
316 requests, selects explicitly a codec for an image to handle. If the
317 codec selected is incapable of saving an error is returned. Selecting a
318 codec is only possible with the object-driven syntax, and this
319 information is never extracted from objects but passed to 'images'
320 array instead.
321 $x-> {extras}-> {codecID} = 1;
323 $x-> save( $f);
324 Actual correspondence between codecs and their indices is described
326 latter.
327 NB - if codecID is not given, codec is selected by the file extension.
329 Type conversion
331 Codecs usually are incapable of saving images in all formats, so Prima
332 either converts an image to an appropriate format or signals an error.
333 This behavior is governed by profile key 'autoConvert', which is 1 by
334 default. 'autoConvert' can be present in image 'extras' structures.
335 With autoConvert set it is guaranteed that image will be saved, but
336 original image information may be lost. With autoConvert unset, no
337 information will be lost, but Prima may signal an error. Therefore
338 general-purpose save routines should be planned carefully. As an
339 example the "Prima::Dialog::ImageDialog::SaveImageDialog" code might be
340 useful.
341 When the conversion takes place, Image property 'conversion' is used
343 for selection of an error distribution algorithm, if down-sampling is
344 required.
345 Appending frames to an existing file
347 This functionality is under design, but the common outlines are already
348 set. Profile key 'append' ( 0 by default ) triggers this behavior - if
349 it is set, then an append attempt is made.
350
352 Prima provides single function, Prima::Image-> codecs, which returns an
353 anonymous array of hashes, where every hash entry corresponds to a
354 registered codec. 'codecID' parameter on load and save requests is
355 actually an index in this array. Indexes for a codecs registered once
356 never change, so it is safe to manipulate these numbers within single
357 program run.
358 Codec information that is contained in these hashes is divided into
360 following parameters:
361 codecID
363 Unique integer value for a codec, same as index of the codec entry
364 in results of "Prima::Image->codecs";
365 name
367 codec full name, string
368 vendor
370 codec vendor, string
371 versionMajor and versionMinor
373 usually underlying library versions, integers
374 fileExtensions
376 array of strings, with file extensions that are typical to a codec.
377 example: ['tif', 'tiff']
378 fileType
380 Description of a type of a file, that codec is designed to work
381 with. String.
382 fileShortType
384 Short description of a type of a file, that codec is designed to
385 work with. ( short means 3-4 characters ). String.
386 featuresSupported
388 Array of strings, with some features description that a codec
389 supports - usually codecs implement only a part of file format
390 specification, so it is always interesting to know, what part it
391 is.
392 module and package
394 Specify a perl module, usually inside Prima/Image directory into
395 Prima distribution, and a package inside the module. The package
396 contains some specific functions for work with codec-specific
397 parameters. Current implementation defines only ::save_dialog()
398 function, that returns a dialog that allows to change these
399 parameters. See "Prima::Dialog::ImageDialog::SaveImageDialog" for
400 details. Strings, undefined if empty.
401 canLoad
403 1 if a codec can load images, 0 if not
404 canLoadStream
406 1 if a codec can load images from streams, 0 otherwise
407 canLoadMultiple
409 1 if a codec can handle multiframe load requests and load frames
410 with index more than zero. 0 if not.
411 canSave
413 1 if a codec can save images, 0 if not.
414 canSaveStream
416 1 if a codec can save images to streams, 0 otherwise
417 canSaveMultiple
419 Set if a codec can save more that one frame
420 canAppend
422 Set if a codec can append frames to an existing file
423 types
425 Array of integers - each is a combination of im:: flags, an image
426 type, which a codec is capable of saving. First type in list is a
427 default one; if image type that to be saved is not in that list,
428 the image will be converted to this default type.
429 loadInput
431 Hash, where keys are those that are accepted by Prima::Image->
432 load, and values are default values for these keys.
433 loadOutput
435 Array of strings, each of those is a name of extra information
436 entry in 'extras' hash.
437 saveInput
439 Hash, where keys are those that are accepted by Prima::Image->
440 save, and values are default values for these keys.
441 mime
443 array of strings, with file extensions that are typical to a codec.
444 example: ['image/xbm', 'image/x-bitmap']
445
447 This section describes parameters accepted and data returned by
448 "Prima::Image::load"
449 Common
451 Loading parameters
452 blending BOOLEAN = 1
454 Affects how to treat alpha channel bits, if any.
455 If set, mixes the alpha channel with background color in case if
457 loading to an image, or premultiplies color bits (either data or
458 palette) with alpha, if loading to icon. Note that saving back the
459 object will result in different image, but the object is ready to
460 be displayed immediately.
461 If unset, color and eventual alpha bits, if loaded to an icon, will
463 not be affected in any way. Note that saving back the object will
464 result in the same image, but the object is not ready to be
465 displayed immediately. See also: "premultiply_alpha" in
466 Prima::Image.
467 className STRING
469 When loading more than one image, this string is used to create
470 instances of image containers. By default the calling class is used
471 (i.e. "Prima::Image" or "Prima::Icon").
472 eventDelay INT
474 Specifies "onDataReady" event granularity in microseconds, if image
475 codec is capable of triggering this event.
476 Default: 100
478 iconUnmask BOOL
480 If set, "Prima::Icon::autoMasking" is set to "am::None" prior to
481 the file loading.
482 Default: false. Only actual for "Prima::Icon" loading.
484 index INT
486 When loading from a multiframe file, selects the frame index to
487 load.
488 Default: 0
490 map [INT]
492 When loading from a multiframe file, selects set of frame indexes
493 to load.
494 Default: undef
496 loadExtras BOOL
498 If set, all available extra information will be stored in
499 "{extras}" hash on the loaded object.
500 Default: false
502 loadAll BOOL
504 When loading from a multiframe file, selects that all frames are to
505 be loaded
506 Default: false
508 noImageData BOOL
510 When set, neither image data is not loaded, nor image dimensions
511 are changed (newly created images have size of 1x1). Instead,
512 "{extras}" contains "width" and "height" integers.
513 Default: false
515 noIncomplete BOOL
517 Affects the action when image is incomplete, truncated, etc. If
518 set, signals an error. Otherwise no error is signaled and whatever
519 data could be recovered from the image are returned, and
520 "truncated" flag is set.
521 Default: false
523 profiles [HASH]
525 Array of hashes passed down to each frame in multiframe loads. Each
526 frame load request will be passed an individual hash, a result of
527 hash join of all profiles passed to "Image::load" and the nth hash
528 in the array.
529 wantFrames BOOL
531 Affects how the number of frames in a file is reported in "frames"
532 flag. If set, always scans the file for exact number. Otherwise it
533 is up to the codec to do that.
534 Default: false
536 See also: frames.
538 Load output
540 codecID INT
542 Indicates the internal codec ID used to load the image. Can be used
543 for "Image::save".
544 frames INT
546 If set to a positive integer, indicates number of frames in a file.
547 Otherwise signals that there are frames, but codec needs an
548 expensive scan to calculate the frames (and "wantFrames" set).
549 height INT
551 When "noImageData" is in action, contains image height.
552 truncated BOOL
554 When "noIncomplete" is in action, is set if image was truncated.
555 The value is the error string.
556 width INT
558 When "noImageData" is in action, contains image width.
559 Saving parameters
561 autoConvert BOOL
563 Affects the action when image cannot be stored in file format in
564 its existing pixel format. If set, the system tries to convert
565 image into a pixel format understood by the selected codec. Fails
566 otherwise.
567 Default: true
569 codecID INT
571 Overrides codec selection based on filename extension.
572 Default: undef
574 BMP codec
576 BMP, the bitmap codec is not depended on external libraries and is
577 always available.
578 BitDepth INT
580 Original bit depth, may differ from "Image::bpp".
581 Not valid as a saving parameter.
583 Compression STRING
585 Bitmap compressing method.
586 Not valid as a saving parameter.
588 HotSpotX, HotSpotY INT
590 If loading from cursor file, contains pointer hotspot coordinates
591 ImportantColors INT
593 Minimal number of colors needed to display the image
594 OS2 BOOL
596 Set when loading OS/2 bitmap
597 XResolution, YResolution INT
599 Image resolution in PPM
600 X11 codec
602 X11, the X Consortium data file codec may depend on external libraries,
603 but is implement internally if these are not found, and is thus always
604 available.
605 hotSpotX, hotSpotY INT
607 Contains pointer hotspot coordinates, if any
608 XPM codec
610 extensions HASH
611 Set of xpm-specific extension strings. Cannot be used for saving.
612 hintsComment, colorsComment, pixelsComment STRING
614 Contains comments to different sections
615 hotSpotX, hotSpotY INT
617 Contains pointer hotspot coordinates
618 transparentColors [COLOR]
620 Array or transparent colors. Cannot be used for saving.
621 JPEG codec
623 Load parameters
624 exifTransform none|auto|wipe
626 If set to "auto" or "wipe", tries to detect whether there is are
627 any exif tags hinting that the image has to be rotated and/or
628 mirrored. If found, applies the transformation accordingly.
629 When set to "wipe", in addition to that, removes the exif tags so
631 that subsequent image save won't result in transformed images with
632 exifs tags still present.
633 This parameter requires "loadExtras" flag set, because exif tags
635 are stored in extra JPEG data.
636 Load output and save input
638 appdata [STRING]
640 Array of raw binary strings found in extra JPEG data.
641 comment STRING
643 Any comment text found in file.
644 progressive BOOL
646 If set, produces a progressively encoded JPEG file.
647 Default: 0
649 Only used for saving.
651 quality INT
653 JPEG quality, 1-100.
654 Default: 75
656 Only used for saving.
658 PNG codec
660 Load input
661 background COLOR
663 When PNG file contains alpha channel, and "alpha" is set to
664 "blend", this color is used to blend the background. If set to
665 "clInvalid", default PNG library background color is used.
666 Default: clInvalid
668 Not applicable for "Prima::Icon".
670 gamma REAL
672 Override gamma value applied to the loaded image
673 Default: 0.45455
675 screen_gamma REAL
677 Current gamma value for the operating system, if specified.
678 Default: 2.2
680 Load output and save input
682 background COLOR
684 Default PNG library background color
685 Default: clInvalid, which means PNG library default
687 blendMethod blend|no_blend|unknown
689 Signals whether the new frame to be blended over the existing
690 animation, or replace it.
691 delayTime $milliseconds
693 Delay time between frames
694 default_frame BOOLEAN
696 When set, means that the first image is a "default" frame, a
697 special backward-compatibility image that is supposed to be
698 excluded from the animation sequence, to be displayed only when all
699 animation frames cannot be loaded for whatever reason.
700 disposalMethod none|background|restore|unknown
702 Signals whether the frame, before being replaced, is to be erased
703 by the background color, previous frame, or none.
704 gamma REAL
706 Gamma value found in file.
707 Default: 0.45455
709 hasAlpha BOOLEAN
711 If set, image contains alpha channel
712 iccp_name, iccp_profile STRING
714 Embedded ICC color profiles in raw format
715 Default: "unspecified" and "".
717 interlaced BOOL
719 If set, PNG file is interlaced
720 Default: 0
722 left INTEGER
724 Frame horizontal offset from the screen
725 loopCount INTEGER
727 How many times the animation sequence should run, or 0 for forever.
728 mng_datastream BOOL
730 If set, file contains a MNG datastream
731 Default: 0
733 offset_x, offset_y INT
735 Positive offset from the left edge of the screen to offset_x and
736 the positive offset from the left edge of the screen to offset_y
737 Default: 0
739 offset_dimension pixel|micrometer
741 Offset units
742 Default: pixel
744 render_intent none|saturation|perceptual|relative|absolute
746 See PNG docs.
747 Default: none
749 resolution_x, resolution_y INT
751 Image resolution
752 Default: 0
754 resolution_dimension meter|unknown
756 Image resolution units
757 Default: meter
759 scale_x, scale_y
761 Image scale factors
762 Default: 1
764 scale_unit meter|radian|unknown
766 Image scale factor units
767 Default: unknown
769 screenWidth, screenHeight INTEGER
771 text HASH
772 Free-text comments found in the file
773 Default: "{}"
775 top INTEGER
777 Frame vertical offset from the screen
778 transparency_table [INT]
780 When a paletted image contains transparent colors, returns array of
781 palette indexes ("transparency_table") in 0-255 range, where each
782 number is an alpha value.
783 Default value: empty array
785 transparent_color COLOR
787 One transparent color value for 24-bit PNG images.
788 Default value: clInvalid (i.e. none)
790 transparent_color_index INT
792 One transparent color value, as palette index for 8- or less- bit
793 PNG images.
794 Default value: -1 (i.e. none)
796 Not applicable for load.
798 TIFF codec
800 Load input
801 MinIsWhite BOOL
803 Automatically invert "PHOTOMETRIC_MINISWHITE" images
804 Default: 1
806 Fax BOOL
808 If set, converts 1-bit grayscale with ratio 2:1 into 2-bit
809 grayscale (algorithm also known as faxpect).
810 Default: 0
812 Load output
814 Photometric STRING
816 TIFF "PHOTOMETRIC_XXX" constant. One of:
817 MinIsWhite
819 MinIsBlack
820 Palette
821 YCbCr
822 RGB
823 LogL
824 LogLUV
825 Separated
826 MASK
827 CIELAB
828 DEPTH
829 Unknown
830 BitsPerSample INT
832 Bits used to represent a single sample, 1-64
833 SamplesPerPixel INT
835 Number of samples per pixel, 1-4. F.ex. most images have 1 sample.
836 Planar TIFFs may split low and high bytes in 2 samples. RGB has 3
837 samples, YCbCr and RGBA has 4.
838 PlanarConfig contiguous|separate
840 "separate" images split individual samples or components (f.ex. R
841 and G and B) into individual planes. "contiguous" mix sample bytes
842 one after another.
843 SampleFormat STRING
845 Pixel sample format, one of:
846 unsigned integer
848 signed integer
849 floating point
850 untyped data
851 complex signed int
852 complex floating point
853 Tiled BOOL
855 If set, TIFF is tiled
856 Faxpect BOOL
858 When "Fax" option set set to "true", and indeed the image was
859 converted from 1 to 2 bits, this parameter will be set to signal
860 this.
861 CompressionType STRING
863 Compression algorithm used for reading TIFF. One of:
864 NONE
866 CCITTRLE
867 CCITTFAX3
868 CCITTFAX4
869 LZW
870 OJPEG
871 JPEG
872 NEXT
873 CCITTRLEW
874 PACKBITS
875 THUNDERSCAN
876 IT8CTPAD
877 IT8LW
878 IT8MP
879 IT8BL
880 PIXARFILM
881 PIXARLOG
882 DEFLATE
883 ADOBE_DEFLATE
884 DCS
885 JBIG
886 SGILOG
887 SGILOG24
888 Save input
890 Compression STRING
892 Same values as in "CompressionType". Different names are used to
893 avoid implicit but impossible compression selection, because
894 tibtiff can decompress many types, but compress only a few.
895 Load output and save input
897 generic strings
899 The following keys have no specific meanings for Prima, but are
900 both recognized for loading and saving:
901 Artist
903 Copyright
904 DateTime
905 DocumentName
906 HostComputer
907 ImageDescription
908 Make
909 Model
910 PageName
911 PageNumber
912 PageNumber2
913 PageNumber, PageNumber2 INT
915 Default: 1
916 ResolutionUnit inch|centimeter|none
918 Default: none
919 Software
921 Default: Prima
922 XPosition, YPosition INT
924 Default: 0
925 XResolution, YResolution INT
927 Default: 1200
928 GIF codec
930 For GIF animation see Prima::Image::Animate.
931 The following load output and save input keys are recognized:
933 comment STRING
935 GIF comment text
936 delayTime INT
938 Delay in hundredth of a second between frames
939 Default: 1
941 disposalMethod INT
943 Animation frame disposal method
944 DISPOSE_NOT_SPECIFIED = 0; # Leave frame, let new frame draw on top
946 DISPOSE_KEEP = 1; # Leave frame, let new frame draw on top
947 DISPOSE_CLEAR = 2; # Clear the frame's area, revealing bg
948 DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame
949 Default: 0
951 interlaced BOOL
953 If set, GIF is interlaced
954 Default: 0
956 left, top INT
958 Frame offset in pixels
959 Default: 0
961 loopCount INT
963 How many times the GIF animation loops. 0 means indefinite.
964 Default: 1
966 screenBackGroundColor COLOR
968 GIF screen background color
969 Default: 0
971 screenColorResolution INT
973 Default: 256
974 screenWidth, screenHeight INT
976 Default: -1, i.e. use image width and height
977 screenPalette [INT]
979 Default: 0,0,0,255,255,255
980 transparentColorIndex INT
982 Index of GIF transparent color
983 Default: 0
985 userInput INT
987 User input flag
988 Default: 0
990 WebP codec
992 Load input
993 background $ARGB_color
995 Integer constant encoded as ARGB, hints the background to be used
996 blendMethod blend|no_blend|unknown
998 Signals whether the new frame to be blended over the existing
999 animation, or replace it.
1000 delayTime $milliseconds
1002 Delay time between frames
1003 disposalMethod none|background|unknown
1005 Signals whether the frame, before being replaced, is to be erased
1006 by the background color or not.
1007 hasAlpha BOOLEAN
1009 If set, image contains alpha channel
1010 left INTEGER
1012 Frame horizontal offset from the screen
1013 loopCount INTEGER
1015 How many times the animation sequence should run, or 0 for forever.
1016 screenWidth INTEGER
1018 screenHeight INTEGER
1019 top INTEGER
1020 Frame vertical offset from the screen
1021 Save input
1023 WebP requires all images to have same dimensions. Also, saving the
1025 webp loading result might fail because loaded frames might only
1026 contains parts to be superimposed on each other, while saving requires
1027 always full frames. To convert webp loaded frames to something that can
1028 be saved later more-or-less identically, use
1029 "Prima::Image::webp::animation_to_frames" converter:
1030 use Prima qw(Image::webp);
1032 my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@;
1033 @i = Prima::Image::webp::animation_to_frames(@i);
1034 die $@ if @i != Prima::Icon->save('target.webp', images => \@i);
1035 background $ARGB_color
1037 Integer constant encoded as ARGB, hints the background to be used
1038 compression lossless (default)|lossy|mixed
1040 delay $milliseconds
1041 filter_strength INTEGER
1042 Setting between 0 and 100, 0 means off.
1043 kmax INTEGER
1045 Min distance between key frames. Default is 9 for lossless
1046 compression, and 3 for lossy
1047 kmin INTEGER
1049 Max distance between key frames. Default is 17 for lossless
1050 compression, and 5 for lossy
1051 loopCount 0
1053 How many times the animation sequence should run, or 0 for forever.
1054 method INTEGER
1056 Compression method vs size, 0 (fast) to 6 (slow)
1057 minimize_size BOOLEAN
1059 Minimize output size (off by default)
1060 quality INTEGER
1062 Quality factor (0:small..100:big)
1063 thread_level BOOLEAN
1065 Use multi-threading if available (off by default)
1066 HEIF codec
1068 Load output
1069 chroma_bits_per_pixel
1071 depth_images
1072 Number of depth images available for the frame
1073 has_alpha
1075 ispe_height, ispe_width
1076 Original image size before tranformations (crop, rotation, etc) are
1077 applied
1078 is_primary
1080 Set if this is the primary image
1081 luma_bits_per_pixel
1083 premultiplied_alpha
1084 Set if alpha is premultiplied
1085 thumbnails
1087 Array of hashes with keys type, content_type, and content.
1088 aux
1090 metadata
1091 thumbnail_of INDEX
1092 Set it is thumbnail of the INDEXth toplevel frame
1093 Save input
1095 quality
1097 0-100
1098 compression
1100 HEIC,AV1,AVC
1101 is_primary
1103 0 gets to be a primary by default, but an be set explicitly
1104 premultiplied_alpha
1106 True if alpha is premultiplied
1107 metadata
1109 Array of hashes with keys type, content_type, and content.
1110 thumbnail_of INDEX
1112 Sets this images as a thumbnail of the INDEXth toplevel frame
1113
1115 Dmitry Karasik, <dmitry@karasik.eu.org>.
1116
1118 Prima, Prima::Image, Prima::codecs
1119perl v5.36.0 2023-03-20 pod::Prima::image-load(3)