NAME

Prima::image-load - using the image subsystem

DESCRIPTION

This document describes using the Prima image subsystem for loading and saving images

Loading

Simple loading

In the simplest case, loading a single image would look like this:

my $x = Prima::Image-> load( 'filename.jpg');
die "$@" unless $x;

Image functions can be invoked either as package functions or as Prima::Image object methods. The code above could be also written as

my $x = Prima::Image-> new;
die "$@" unless $x-> load( 'filename.jpg');

In both cases, $x contains loaded image data upon success. If an error occurs, it is returned in the $@ variable ( see perlvar ).

Loading from stream

Prima::Image can also load images by reading from a stream:

	open FILE, 'a.jpeg' or die "Cannot open:$!";
	binmode FILE;
	my $x = Prima::Image-> load( \*FILE);
        die "$@" unless $x;

Multiframe loading

Multiframe load calls can be issued in two ways:

my @x = Prima::Image-> load( 'filename.gif', loadAll => 1);
die "$@" unless $x[-1];

my $x = Prima::Image-> new;
my @x = $x-> load( 'filename.gif', loadAll => 1);
die "$@" unless $x[-1];

In the second case, the content of the first frame is stored in $x and $x[0]. To check if the error has occurred during the loading, inspect the last item of the returned array; it is undefined if the error indeed occurred. This check works also if an empty array is returned. Only this last item can be undefined, others are guaranteed to be valid objects.

Prima can load more than one image from a file, assuming the image format allows that. The load function recognizes such multiframe semantics when certain extra hash keys are used. These keys are:

loadAll

Requests to load all frames that can be read from the file:

loadAll => 1

index

If present, returns a single frame with the index given:

index => 8

map

Contains an anonymous array of the frame indices to load. The indices must be integers that are greater or equal to zero:

map => [0, 10, 15..20]

Querying extra information

By default, Prima loads only image pixels and palette. For any other information that can be loaded, use the hash 'extras' bound to the image object. To notify the image loader that this extra information is expected, the loadExtras boolean value is used:

my $x = Prima::Image-> load( $f, loadExtras => 1);
die "$@" unless $x;
for ( keys %{$x-> {extras}}) {
   print " $_ : $x->{extras}->{$_}\n";
}

The code above loads and prints extra information read from a file. Typical output, for example, from a gif codec based on the libgif library would look like this:

codecID : 1
transparentColorIndex : 1
comment : created by GIMP
frames : 18

codecID is a Prima-defined integer field, an internal index of the codec which had previously loaded the file. This value is useful for the explicit selection of the codec to be used for saving an image.

frames is also a Prima-defined field, with its integer value set to the number of frames in the image. It might be set to -1 signaling that the codec is incapable of quick reading of the frame count. If, however, it is necessary to get the actual frame count, the wantFrames boolean value should be set to 1 - then the frames field is guaranteed to be set to a 0 or a positive value. Such a request may take longer though, especially on large files with sequential access. A real-life example is a gif file with more than a thousand frames. The wantFrames flag is also useful in null load requests (see below).

Multiprofile loading requests

The parameters that are accepted by the load function are divided into two groups - first, those that apply to the whole loading process, and then those that apply only to a particular frame. Some fields that were already mentioned (wantFrames and loadAll) belong to the first group because they affect the whole loading session. Some other parameters (loadExtras, noImageData, noIncomplete, iconUnmask) can be applied to each loaded frame, individually. A codec may as well define its own parameters, however, it is not possible to tell what parameter belongs to what group - this information is to be found in the codec documentation.

The parameters that apply to a frame, can be specified separately for every frame in a single call. For that purpose, the special parameter profiles is defined. The profiles value is expected to be an anonymous array of hashes, where each hash corresponds to a request number. For example:

$x-> load( $f, loadAll => 1, profiles => [
     {loadExtras => 0},
     {loadExtras => 1},
]);

The first hash there applies to the frame index 0, second - to the frame index 1. Note that in the code below

$x-> load( $f,
   map => [ 5, 10],
   profiles => [
     {loadExtras => 0},
     {loadExtras => 1},
]);

first hash applies to the frame index 5, and second - to the frame index 10.

Null load requests

If it is desired to quickly peek into an image, reading only its pixel type and dimensions, one should set the noImageData boolean value to 1. Using noImageData, empty image objects are returned, that would have the type property set to the image type (as the codec would translate it to the Prima image type), and with the extras width and height set to the image dimensions. Example:

$x-> load( $f, noImageData => 1);
die "$@" unless $x;
print $x-> {extras}-> {width} , 'x' , $x-> {extras}-> {height}, 'x',
   $x-> type & im::BPP, "\n";

Some image information can be loaded even without frame loading - if the codec provides such a functionality. This is the only request that cannot be issued with the package syntax, an existing image object is required:

	my $x = Prima::Image->new;
        $x-> load( $f, map => [], loadExtras => 1);

Since no frames are required to load, an empty array is returned on success and an array with one undefined value on failure.

Using Prima::Image descendants

If Prima needs to create a storage object, it uses by default either the class name of the caller object, or the package the request was issued on, or the Prima::Image class. This behavior can be altered using the parameter className, which defines the class to be used for each frame:

my @x = Prima::Image-> load( $f,
    map => [ 1..3],
    className => 'Prima::Icon',
    profiles => [
        {},
        { className => 'Prima::Image' },
        {}
    ],

In this example, @x will contain (Icon, Image, Icon) upon success.

When loading to an Icon object, the default toolkit action is to build the transparency mask based on the image data. When this is not desired, f.ex., there is no explicit knowledge of the image to be loaded, while the image may or may not contain transparency information, the iconUnmask boolean parameter can be used. When set to the true value, and the object is a Prima::Icon descendant, Prima::Icon::autoMasking is set to am::None before the file loading which effectively disables any attempt to generate the icon mask. By default, this option is turned off.

Loading with the progress indicator

Some codecs (PNG,TIFF,JPEG) can signal their progress as they read image data. For this purpose, the Prima::Image class defines two events, onHeaderReady and onDataReady. If either (or both) are present on the image object issuing the load call, and the codec supports progressive loading, then these events will be called. The onHeaderReady event is called when the image header data is acquired, and an empty image with the required pixel dimensions and type is allocated. The onDataReady notification is called whenever a part of the image is ready and is loaded in the memory of the object; the position and dimensions of the loaded area are reported also. The format of the events is as follows:

onHeaderReady $OBJECT
onDataReady   $OBJECT, $X, $Y, $WIDTH, $HEIGHT

The onHeaderReady event is called only once while onDataReady is called as soon as new image data is available. To reduce the frequency of these calls, which otherwise would be issued after every scanline loaded, load has the parameter eventDelay, the minimum number of seconds that need to pass between two consecutive onDataReady calls. The default eventDelay is 0.1 .

The handling of the onDataReady event must be performed with care. First, the image must be accessed read-only, i e no transformations of any kind are allowed. Currently, there is no protection for such actions ( because the codec must also perform these itself), so a crash will most surely issue. Second, loading and saving of images is not in general reentrant, and although some codecs are reentrant, loading and saving images inside image events is not recommended.

There are two techniques to display the image progressively. Both of them require overloading the onHeaderReady and onDataReady callbacks. The simpler case is to call the put_image method from inside onDataReady:

$i = Prima::Image-> new(
	onDataReady => sub {
		$progress_widget-> put_image( 0, 0, $i);
	},
);

but that will most probably load heavily underlying OS-dependent conversion of the image data to native display bitmap data. A smarter, but more complex solution is to copy loaded (and only loaded) bits to a preexisting bitmap or image:

$i = Prima::Image-> new(
	onHeaderReady => sub {
		$bitmap = Prima::DeviceBitmap-> new(
			width    => $i-> width,
			height   => $i-> height,
		));
	},
	onDataReady => sub {
		my ( $i, $x, $y, $w, $h) = @_;
		$bitmap-> put_image( $x, $y, $i-> extract( $x, $y, $w, $h));
	},
);

The latter technique is used by the Prima::ImageViewer widget class when it is ordered to monitor the image loading progress. See "watch_load_progress" in Prima::ImageViewer for details.

Truncated files

By default, codecs are not told whether they would fail on the premature end of the file or omit the error and return a truncated image. The noIncomplete boolean parameter tells that a codec must always fail if the image cannot be read in full. It is off by default. If indeed the codec detects that the file is incomplete, it sets the truncated field in the extras profile, if loadExtras was requested; the field is a string and contains the error message that occurred when the codec tried to load the truncated field.

Inline files

Using the Prima::Image::base64 module it is possible to convert images into the base64 format and embed the result directly into the source code. Assuming an appropriate codec was compiled in, the following would work:

my $icon = Prima::Icon->load_stream(<<~'ICON');
	R0lGODdhIAAgAIAAAAAAAP///ywAAAAAIAAgAIAAAAD///8CT4SPqcvtD6OctNqLcwogcK91nEhq
	3gim2Umm4+W2IBzX0fvl8jTr9SeZiU5E4a1XLHZ4yaal6XwFoSwMVUVzhoZSaQW6ZXjD5LL5jE6r
	DQUAOw==
	ICON
print $icon->save_stream;

Reading one frame at a time

When one needs to load all frames from an image that contains too many frames, or there is a constraint on memory, Prima provides a way to load images one by one, without needing to allocate space for all frames in the file.

This section describes the lower-level API that allows for that functionality, however, an easier-to-use higher level API is documented in Prima::Image::Loader .

In order to read one frame at a time, the programmer needs to open a loading session, by adding the session => 1 option to the load call; that call can only be made on an existing object, not on the package. The call would return the success flag and an eventual error in $@, as usual. No frames are loaded yet, though the extras hash on the caller image object may be filled, depending on the loadExtras option. The options supplied to the session opening call would apply to all subsequent frames, but these settings may be overridden later.

Having the session successfully opened, the subsequent calls to load with the session => 1 option but with the first parameter set to undef will load the next frame. Each of those load call will recognize the options supplied and will apply them to indifidual frames. The session-based loading will recognize all of the function options, except the map, profiles and loadAll options. The loading session is closed automatically after either a first loading failure or after the end of file is reached.

Saving

Simple saving

The typical saving code is

$x-> save( 'filename.jpg') or die $@;

The function returns 1 on success and 0 on failure. Save requests also can be performed with the package syntax:

die "$@" unless Prima::Image-> save( 'filename.jpg',
    images => [$x]);

Saving to a stream

Saving to a stream requires the explicit codecID integer value to be supplied. When the image is loaded with loadExtras, this field is always present on the image object and is the integer that selects the image file format.

my ($png_id) =
   map  { $_-> {codecID} }
   grep { $_-> {fileShortType} =~ /^png$/i }
   @{ Prima::Image-> codecs };
die "No png codec installed" unless $png_id;

open FILE, ">", "a.png" or die "Cannot save:$!";
binmode FILE;
$image-> save( \*FILE, codecID => $png_id)
   or die "Cannot save:$@";

Multiframe saving

When saving more than one image object into a single file the method returns the number of successfully saved frames. The saved image file is erased though, if an error occurs, even after some successfully written frames.

die "$@" if scalar(@images) > Prima::Image-> save( $f,
   images => \@images);

Saving extras information

All information that is found in the object hash reference extras, is assumed to be saved in the image file too. It is a codec's own business how it reacts to invalid and/or unacceptable information - but a typical behavior is that keys that were not recognized by the codec get ignored, while invalid values raise an error.

$x-> {extras}-> {comments} = 'Created by Prima';
$x-> save( $f);

Saving one frame at a time

Similar to the session-based loading, Prima provides the functionality to save a multi-frame image with one frame at a time, using the similar API calls.

This section describes the lower-level API that allows for that functionality, however, an easier-to-use higher level API is documented in "Prima::Image::Saver" in Prima::Image::Loader .

In order to save one frame at a time, the programmer needs to open a saving session, by adding the session => 1 option to the save call, and the frames options that signals how many frames are to be saved in total; that call can only be made on an existing object, not on the package. The call would return the success flag and an eventual error in $@, as usual. The options supplied to the session opening call would apply to all subsequent frames, but these settings may be overridden later.

Having the session successfully opened, the subsequent calls to save with the session => 1 and the image as the first option option would save the next frame. Each of those save call will recognize the options supplied and will apply them to indifidual frames. The session-based saving will recognize all of the function options, except the images option. The saving session is closed automatically after a first failure.

Selecting a codec

The integer field codecID, the same field that is defined after successful load requests, explicitly selects the codec for saving the image. If the codec is incapable of saving then an error is returned. Selecting a codec is only possible with the object-driven syntax, and this information is never extracted from the objects but is passed in the images array instead.

$x-> {extras}-> {codecID} = 1;
$x-> save( $f);

The actual relation between codecs and their indices is described below.

Note: if codecID is not specified, Prima tries to deduce the codec by the file extension.

Type conversion

Codecs usually are incapable of saving images in all possible pixel formats, so whenever Prima needs to save an image with an unsupported pixel type it either converts the image to an appropriate pixel format or signals an error. This behavior is managed by the parameter autoConvert, which is 1 by default. With the autoConvert set, it is guaranteed that the image will be saved, but original image information may be lost. With the autoConvert field set to 0, no information will be lost, but Prima may signal an error. Therefore general-purpose saving routines should be planned carefully. As an example, the Prima::Dialog::ImageDialog::SaveImageDialog code might be useful.

When the conversion takes place, the Image property conversion is used for the selection of the error distribution algorithm if down-sampling is required.

Managing the codecs

Prima provides the Prima::Image-> codecs function that returns an anonymous array of hashes where every hash entry corresponds to a registered codec. The codecID parameter on load and save requests is the index in this array. Indexes for the codecs registered once never change, so it is safe to manipulate these numbers within a single run of the program

Codec information that is contained in these hashes contains the following fields:

codecID: A unique integer value for a codec, the same as the index of the codec entry in the result of the Prima::Image->codecs method
name: The full codec name, string
vendor: The codec vendor, string
versionMajor and versionMinor: Usually underlying library versions, integers
fileExtensions: An array of strings, with file extensions that are typical to the codec. Example: ['tif', 'tiff']
fileType: Description of the type of file that the codec is designed to work with. A string.
fileShortType: Short description of the type of file that the codec is designed to work with ( short means 3-4 characters ). A string.
featuresSupported: An array of strings containing string description of the features that the codec supports - usually they implement only a part of file format specification, so it is always interesting to know, which part
module and package: Specifies the perl module, usually inside the Prima/Image directory in the Prima distribution, and the package name inside the module. The package contains some specific functions for working with codec-specific parameters. The current implementation defines the only save_dialog function that creates a dialog that allows to change these parameters. See Prima::Dialog::ImageDialog::SaveImageDialog for details. Strings or undef.
canLoad: 1 if the codec can load images, 0 if not
canLoadStream: 1 if the codec can load images from streams, 0 otherwise
canLoadMultiple: 1 if the codec can handle multiframe load requests and load frames with an index more than zero, 0 otherwise
canSave: 1 if the codec can save images, 0 if not.
canSaveStream: 1 if the codec can save images to streams, 0 otherwise
canSaveMultiple: Is set if the codec can save more than one frame
types: An array of integers - each is a combination of the im::XXX flags, the image type, that the codec can save. The first type in the list is the default type; if the type of the image to be saved is not in that list, the image will be converted to this default type.
loadInput: A hash, where the keys are those that are accepted by the Prima::Image-> load method and the values are the default values for these keys.
loadOutput: An array of strings, each is the name of an extra information entry in the extras hash.
saveInput: A hash, where the keys are those that are accepted by the Prima::Image-> save method and the values are the default values for these keys.
mime: An array of strings, containing the mime identifiers specific to the image format. An example: ['image/xbm', 'image/x-bitmap']

API

This section describes the parameters accepted and the data returned by the Prima::Image::load method

Common

Loading parameters

blending BOOLEAN = 1

Affects how to treat the alpha channel bits, if present.

If set, mixes the alpha channel with the background color in case when loading to an image, or premultiplies color bits (either data or palette) with alpha, when loading to an icon. Note that saving the object will result in different image pixel values, but the object will be ready to be displayed immediately.

If unset, the color and eventual alpha bits, if loaded to an icon, will not be affected in any way. Note that saving the object will result in the same image, but the object will not be ready to be displayed immediately. See also: "premultiply_alpha" in Prima::Image.

className STRING

When loading more than one image, this string is used to create instances of image containers. By default, the calling class is used (i.e. Prima::Image or Prima::Icon).

eventDelay INT

Specifies onDataReady event granularity in seconds, when the codec is capable of triggering this event.

Default: 0.1

iconUnmask BOOL

If set, Prima::Icon::autoMasking is set to am::None before the file loading which disables any attempt to deduce the mask pixels based on the data pixels.

Default: false. Only actual for Prima::Icon loading.

index INT

When loading from a multiframe file, selects the frame index to load.

Default: 0

loadExtras BOOL

If set, all available extra information will be stored in the extras hash on the loaded object.

Default: false

loadAll BOOL

When loading from a multiframe file, selects that all frames are to be loaded

Default: false

map [INT]

When loading from a multiframe file, selects the set of the frame indexes to load.

Default: undef

noImageData BOOL

If set, neither image data is loaded, nor image dimensions are changed (newly created images have a size of 1x1). Instead, the {extras} hash contains width and height integers.

Default: false

noIncomplete BOOL

Affects the action when the image is incomplete, truncated, etc. If set, signals an error. Otherwise, no error is signaled and whatever data could be recovered from the image is returned. In the latter case, the truncated field contains the error string.

Default: false

profiles [HASH]

An array of hashes passed down to each frame in multiframe loading sessions. Each frame loading request will be provided with an individual hash, a result of the hash join of all profiles passed to Image::load and the nth hash in the array.

wantFrames BOOL

Affects how the number of frames in a file is reported in the frames field. If set, Prima always scans the file for the exact number of frames. Otherwise, it is up to the codec to do that.

Default: false

Load output

codecID INT: Indicates the internal codec ID used to load the image. Can be used for Image::save.
frames INT: If set to a positive integer, indicates the number of frames in the file. Otherwise signals that there are frames, but the codec needs an expensive scan to calculate the number (and the wantFrames parameter being set).
height INT: When the noImageData parameter is set, contains the image height.
truncated BOOL: When the noIncomplete parameter is set, will be set if the image was truncated. The value is the error string.
width INT: When the noImageData parameter is set, contains the image width.

Saving parameters

autoConvert BOOL

Affects the action when the image cannot be stored in a file in its existing pixel format. If set, the system tries to convert the image into one of the pixel formats supported by the selected codec. Fails otherwise.

Default: true

codecID INT

Disables the algorithm where the codec is selected based on the filename extension. Uses the codec number codecID instead. Note that when saving images into streams this option must always be present.

Default: undef

BMP codec

BMP, the bitmap codec is not dependent on external libraries and is always available.

BitDepth INT

Original bit depth may differ from Image::bpp.

Not valid as a saving parameter.

Compression STRING

Bitmap compression method.

Not valid as a saving parameter.

HotSpotX, HotSpotY INT

If loading from a cursor file, contains pointer hotspot coordinates

ImportantColors INT

The minimal number of colors is needed to display the image

OS2 BOOL

Is set when loading an OS/2 bitmap

XResolution, YResolution INT

Image resolution in PPM

X11 codec

X11, the X Consortium data file codec is implemented internally and is always available.

hotSpotX, hotSpotY INT: Contains pointer hotspot coordinates, if any

XPM codec

extensions HASH: A set of xpm-specific extension strings. Cannot be used for saving.
hintsComment, colorsComment, pixelsComment STRING: Contains comments on different sections
hotSpotX, hotSpotY INT: Contains the pointer hotspot coordinates
transparentColors [COLOR]: An array of transparent colors. Cannot be used for saving.

JPEG codec

Load parameters

exifTransform none|auto|wipe

If set to auto or wipe, tries to detect whether there are any exif tags hinting that the image has to be rotated and/or mirrored. If found, applies the transformation accordingly.

When set to wipe, in addition to that, removes the exif tags so that subsequent image save won't result in transformed images with exifs tags still present.

This parameter requires a loadExtras parameter set because exif tags are stored in extra JPEG data.

Output fields of the loader and input parameters for the saver

appdata [STRING]

An array of raw binary strings found in extra JPEG data.

comment STRING

Any comment text found in the file.

progressive BOOL

If set, produces a progressively encoded JPEG file.

Default: 0

Only used for saving.

quality INT

JPEG quality, 1-100.

Default: 75

Only used for saving.

PNG codec

Load input

background COLOR

When a PNG file contains an alpha channel, and alpha is set to blend, this color is used to blend the background. If set to clInvalid, the default PNG library background color is used.

Default: clInvalid

Not applicable to Prima::Icon.

gamma REAL

Override gamma value applied to the loaded image

Default: 0.45455

screen_gamma REAL

Current gamma value for the operating system, if specified.

Default: 2.2

Load output and save input

background COLOR

Default PNG library background color

Default: clInvalid, which means PNG library default

blendMethod blend|no_blend|unknown

Signals whether the new frame is to be blended over the existing animation, or it should replace that.

delayTime $milliseconds

Delay between frames

default_frame BOOLEAN

When set, means that the first image is the "default" frame, a special backward-compatibility image that is supposed to be excluded from the animation sequence, to be displayed only when all animation frames cannot be loaded for whatever reason.

disposalMethod none|background|restore|unknown

Signals whether the frame, before being replaced, is to be erased by the background color, or by the previous frame, or not touched at all.

gamma REAL

Gamma value found in the file.

Default: 0.45455

hasAlpha BOOLEAN

If set, the image contains an alpha channel

iccp_name, iccp_profile STRING

Embedded ICC color profiles in raw format

Default: unspecified and "".

interlaced BOOL

If set, the PNG file is interlaced

Default: 0

left INTEGER

The horizontal offset of the frame from the screen

loopCount INTEGER

How many times the animation sequence should run, or 0 for forever

mng_datastream BOOL

If set, the file contains an MNG datastream

Default: 0

offset_x, offset_y INT

A positive offset from the left edge of the screen to offset_x and the positive offset from the left edge of the screen to offset_y

Default: 0

offset_dimension pixel|micrometer

Offset units

Default: pixel

render_intent none|saturation|perceptual|relative|absolute

See the PNG docs ( http://www.libpng.org/pub/png/spec/1.1/PNG-Chunks.html, 4.2.9. sRGB Standard RGB color space).

Default: none

resolution_x, resolution_y INT

Image resolution

Default: 0

resolution_dimension meter|unknown

Image resolution units

Default: meter

scale_x, scale_y

Image scale factors

Default: 1

scale_unit meter|radian|unknown

Image scale factor units

Default: unknown

screenWidth, screenHeight INTEGER

text HASH

Free-text comments found in the file

Default: {}

top INTEGER

The vertical offset of the frame from the screen

transparency_table [INT]

When a paletted image contains transparent colors, returns an array of palette indexes (transparency_table) in the 0-255 range, where each number is an alpha value.

Default value: empty array

transparent_color COLOR

One transparent color value for 24-bit PNG images.

Default value: clInvalid (i.e. none)

transparent_color_index INT

One transparent color value, as the palette index for 8- or less-bit PNG images.

Default value: -1 (i.e. none)

Not applicable for load.

TIFF codec

Load input

MinIsWhite BOOL

Automatically invert PHOTOMETRIC_MINISWHITE images

Default: 1

Fax BOOL

If set, converts 1-bit grayscale with ratio 2:1 into 2-bit grayscale (algorithm also known as faxpect).

Default: 0

Load output

Photometric STRING

TIFF PHOTOMETRIC_XXX constant. One of:

MinIsWhite
MinIsBlack
Palette
YCbCr
RGB
LogL
LogLUV
Separated
MASK
CIELAB
DEPTH
Unknown

BitsPerSample INT

Bits used to represent a single sample, 1-64

SamplesPerPixel INT

Number of samples per pixel, 1-4. Most images have 1 sample. Planar TIFFs may split low and high bytes in 2 samples. RGB has 3 samples, and YCbCr and RGBA have 4.

PlanarConfig contiguous|separate

separate images split individual samples or components (f.ex. R and G and B) into individual planes. contiguous mix sample bytes one after another.

SampleFormat STRING

Pixel sample format, one of:

unsigned integer
signed integer
floating point
untyped data
complex signed int
complex floating point

Tiled BOOL

If set, TIFF is tiled

Faxpect BOOL

When the Fax option was set to true, and indeed the image was converted from 1 to 2 bits, this parameter will be set to signal this.

CompressionType STRING

The compression algorithm used for reading. One of:

NONE
CCITTRLE
CCITTFAX3
CCITTFAX4
LZW
OJPEG
JPEG
NEXT
CCITTRLEW
PACKBITS
THUNDERSCAN
IT8CTPAD
IT8LW
IT8MP
IT8BL
PIXARFILM
PIXARLOG
DEFLATE
ADOBE_DEFLATE
DCS
JBIG
SGILOG
SGILOG24

Save input

Compression STRING: Same values as in CompressionType. Different names are used to avoid implicit but impossible compression selection because tibtiff can decompress many types, but compress only a few.

Load output and save input

generic strings

The following keys have no specific meanings for Prima, but are both recognized for loading and saving:

Artist
Copyright
DateTime
DocumentName
HostComputer
ImageDescription
Make
Model
PageName
PageNumber
PageNumber2

PageNumber, PageNumber2 INT

Default: 1

ResolutionUnit inch|centimeter|none

Default: none

Software

Default: Prima

XPosition, YPosition INT

Default: 0

XResolution, YResolution INT

Default: 1200

GIF codec

For GIF animation see Prima::Image::Animate.

The following load output and save input keys are recognized:

comment STRING

GIF comment text

delayTime INT

Delay in a hundredth of a second between frames

Default: 1

disposalMethod INT

Animation frame disposal method

DISPOSE_NOT_SPECIFIED    = 0; # Leave frame, let new frame draw on top
DISPOSE_KEEP             = 1; # Leave frame, let new frame draw on top
DISPOSE_CLEAR            = 2; # Clear the frame's area, revealing bg
DISPOSE_RESTORE_PREVIOUS = 3; # Restore the previous (composited) frame

Default: 0

interlaced BOOL

If set, the GIF image is interlaced

Default: 0

left, top INT

Frame offset in pixels

Default: 0

loopCount INT

How many times do the GIF animation loops. 0 means indefinite.

Default: 1

screenBackGroundColor COLOR

GIF screen background color

Default: 0

screenColorResolution INT

Default: 256

screenWidth, screenHeight INT

Default: -1, i.e. use image width and height

screenPalette [INT]

Default: 0,0,0,255,255,255

transparentColorIndex INT

Index of the GIF transparent color

Default: 0

userInput INT

User input flag

Default: 0

WebP codec

Load output

background $ARGB_color: An integer constant encoded as 32-bit ARGB, hints the background color to be used
blendMethod blend|no_blend|unknown: Signals whether the new animation frame is to be blended over the existing animation, or it should replace that.
delayTime $milliseconds: Delay time between frames
disposalMethod none|background|unknown: Signals whether the frame, before being replaced, is to be erased by the background color or not.
hasAlpha BOOLEAN: If set, the image contains an alpha channel
left INTEGER: The horizontal offset of the frame from the screen
loopCount INTEGER: How many times the animation sequence should run, or 0 for forever.
screenWidth INTEGER
screenHeight INTEGER
top INTEGER: The vertical offset of the frame from the screen

Save input

WebP requires all images to have the same dimensions. Also, saving the webp loading result might fail because loaded frames might only contain parts to be superimposed on each other while saving always requires full frames. To convert the loaded frames to something that can be saved later more-or-less identically, use the Prima::Image::webp::animation_to_frames converter:

use Prima qw(Image::webp);
my @i = Prima::Icon->load('source.webp', loadAll => 1, loadExtras => 1) or die $@;
@i = Prima::Image::webp::animation_to_frames(@i);
die $@ if @i != Prima::Icon->save('target.webp', images => \@i);

background $ARGB_color: An integer constant encoded as 32-bit ARGB, hints the background to be used
compression lossless (default)|lossy|mixed
delay $milliseconds
filter_strength INTEGER: The value is between 0 and 100, where 0 means off.
kmax INTEGER: Min distance between keyframes. The default is 9 for the lossless compression and 3 for the lossy
kmin INTEGER: Max distance between keyframes. The default is 17 for the lossless compression and 5 for the lossy
loopCount 0: How many times the animation sequence should run, or 0 for forever.
method INTEGER: Compression method vs size, 0 (fast) to 6 (slow)
minimize_size BOOLEAN: Minimize the output size (off by default)
quality INTEGER: Quality factor (0:small..100:big)
thread_level BOOLEAN: Use multi-threading if available (off by default)

HEIF codec

Load output

chroma_bits_per_pixel
depth_images: Number of depth images available for the frame
has_alpha
ispe_height, ispe_width: Original image size before transformations (crop, rotation, etc) are applied
is_primary: Set if this is the primary image
luma_bits_per_pixel
premultiplied_alpha: Is set if the values of the alpha channel are premultiplied
thumbnails: An array of hashes with keys type, content_type, and content.
aux
metadata
thumbnail_of INDEX: Set if this frame is the thumbnail of the INDEXth top-level frame

Save input

quality: Integer, 0-100
compression: HEIC,AV1,AVC
is_primary: The first frame (#0) gets to be the primary by default, but this can be changed explicitly.
premultiplied_alpha: Trueset if the values of the alpha channel are premultiplied
metadata: An array of hashes with keys type, content_type, and content.
thumbnail_of INDEX: Sets this image as the thumbnail of the INDEXth top-level frame

AUTHOR

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

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

DESCRIPTION

Loading

Simple loading

Loading from stream

Multiframe loading

Querying extra information

Multiprofile loading requests

Null load requests

Using Prima::Image descendants

Loading with the progress indicator

Truncated files

Inline files

Reading one frame at a time

Saving

Simple saving

Saving to a stream

Multiframe saving

Saving extras information

Saving one frame at a time

Selecting a codec

Type conversion

Managing the codecs

API

Common

Loading parameters

Load output

Saving parameters

BMP codec

X11 codec

XPM codec

JPEG codec

Load parameters

Output fields of the loader and input parameters for the saver

PNG codec

Load input

Load output and save input

TIFF codec

Load input

Load output

Save input

Load output and save input

GIF codec

WebP codec

Load output

Save input

HEIF codec

Load output

Save input

AUTHOR

SEE ALSO

Module Install Instructions