pod::Pr...ge-load(3)

📦
version 1.74000 · 5 versions
, in opensuse-leap 16.0

🌸 NAME 🌸

Prima::image-load — using the image subsystem 💖

okay so real talk, bestie: this whole page lives at pod::Prima::image-load(3) and it's from the User Contributed Perl Documentation, and it's literally your glow-up guide to driving the Prima image subsystem around. no cap. 🫶

✨ DESCRIPTION ✨

This document describes using the Prima image subsystem for loading and saving images. that's the whole vibe — we're moving pictures in and out of Prima and looking cute doing it. 🎀

🧚 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. so 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). not me checking $@ every single time, but like… do it. 😌

🌈 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. so like, peek at the last one only, bestie, the rest are trusted. 💀

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. iykyk. 🎯

"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). consider yourself warned, it's giving "patience is a virtue" energy. 🙈

🫶 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. (go read the codec docs, bestie, they told me to tell you.) 📖

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. cute how that works, right?? 💖

🍓 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. yes, empty array = slay, undefined value = not slay. ⭐

👑 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. main character lineup fr fr. 🌟

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.

like seriously bestie, read that box twice. no touching, no saving, no transforming. we are NOT crashing today. 💀💅

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

okay so by default, codecs get zero heads-up about whether they'd fail on a premature end of file or just quietly skip the error and hand you back a truncated image 🫠. The noIncomplete boolean parameter is the fix: it tells the codec "bestie, you MUST always fail if the image can't be read in full." It's off by default. And if the codec does catch that the file is incomplete, it sets the truncated field in the extras profile — but only if loadExtras was requested. That field is a string, and it contains the error message that occurred when the codec tried to load the truncated field. iykyk 💅

Inline files

Using the Prima::Image::base64 module it is possible to convert images into base64 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 you need to load <italics>all</italics> the frames from an image that contains, like, way too many frames, or you're under a memory constraint, Prima provides a way to load images one by one — no need to allocate space for every single frame 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.

So to read one frame at a time, the programmer opens a loading session by adding the session => 1 option to the load call. Heads up: that call can only be made on an existing object, not on the package 🙈. The call returns 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 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 calls will recognize the options supplied and apply them to individual frames. Session-based loading recognizes all of the function options, except the map, profiles and loadAll options 🚫. The loading session closes automatically after either a first loading failure or after the end of file is reached. iconic behavior honestly ✨

💾 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. Careful though 🚨 — the saved image file is erased if an error occurs, even after some frames were successfully written. no cap.

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

Saving extras information

All information found in the object hash reference extras is assumed to be saved in the image file too. It's a codec's own business how it reacts to invalid and/or unacceptable information — but a typical behavior is that keys the codec didn't recognize 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 session-based loading, Prima provides the functionality to save a multi-frame image one frame at a time, using 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 opens a saving session by adding the session => 1 option to the save call, plus the frames option 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 returns the success flag and an eventual error in $@, as usual. The options supplied to the session-opening call apply to all subsequent frames, but these settings may be overridden later.

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

Selecting a codec

The integer field codecID — the same field that's 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. iykyk 🎀

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 autoConvert set, it's 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 codecs registered once never change, so it's safe to manipulate these numbers within a single run of the program 🔥

Codec information 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 the file format specification, so it's 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 changing 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 🦋

  • alpha BOOL — okay so this one's the glow-up switch ✨ Set it and the alpha channel gets mixed with the background color when you're loading to an image, or the color bits (data or palette, both!) get premultiplied with alpha when you're loading to an icon. Heads up though: saving the object afterwards gives you different image pixel values, but the object is ready to be displayed immediately, no extra steps. Leave it unset and the color plus any eventual alpha bits (if loaded to an icon) stay untouched, zero changes. But then saving gives you the same image while the object is not ready to display right away. See also: premultiply_alpha in Prima::Image.
  • className STRING — when you're loading more than one image, this string is what gets used to create the instances of image containers. Default is the calling class, i.e. Prima::Image or Prima::Icon.
  • eventDelay INT — sets the granularity of the onDataReady event in seconds, y'know, when the codec is actually capable of triggering it.

Default: 0.1

  • iconUnmask BOOL — set it and Prima::Icon::autoMasking gets set to am::None before the file loading happens, which disables literally any attempt to deduce mask pixels from the data pixels.

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

  • index INT — loading from a multiframe file? This picks which frame index you get.

Default: 0

  • loadExtras BOOL — set it and all the available extra info goes into the extras hash on the loaded object. Little bonus bag 🎀

Default: false

  • loadAll BOOL — multiframe file again, and this one selects that all frames are to be loaded. all of them. every single one 💅

Default: false

  • map [INT] — multiframe file, selects the set of frame indexes to load. Cherry-picking, we love it.

Default: undef

  • noImageData BOOL — set it and neither image data is loaded nor image dimensions are changed (newly created images have a size of 1x1, tiny legend behavior). Instead, the {extras} hash contains width and height integers.

Default: false

  • noIncomplete BOOL — this controls what happens when the image is incomplete, truncated, etc. If it's set, it signals an error. Otherwise no error is signaled and whatever data could be recovered from the image is returned — in that case the truncated field holds the error string.

Default: false

  • profiles [HASH] — an array of hashes passed down to each frame in multiframe loading sessions. Every frame loading request gets its own individual hash, which is the result of the hash join of all the profiles passed to Image::load plus the *n*th hash in the array. very "everyone gets a party favor" of it 🫶
  • wantFrames BOOL — affects how the number of frames in a file gets reported in the frames field. If set, Prima always scans the file for the exact number of frames. Otherwise it's up to the codec to do that (and sometimes it just won't, iykyk).

Default: false

See also: frames.

💫 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 it signals that there are frames, but the codec needs an expensive scan to calculate the number (and the wantFrames parameter is set). 😭 expensive scan, no thanks
  • 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 — controls what happens when the image can't 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. Otherwise it fails.

Default: true

  • codecID INT — disables the whole 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 — non-negotiable bestie, it's required.

Default: undef

🎨 BMP codec

BMP, the bitmap codec, is not dependent on external libraries and is always available. self-sufficient icon behavior, honestly 👑

  • 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 the pointer hotspot coordinates.
  • ImportantColors INT — the minimal number of colors that 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. never not around 💜

  • hotSpotX, hotSpotY INT — contains the 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, it tries to detect whether there are any exif tags hinting that the image has to be rotated and/or mirrored. If it finds any, it applies the transformation accordingly.

When set to wipe, in addition to that, it removes the exif tags so a subsequent image save won't give you transformed images with exif tags still present. clean slate, we love to see it 🧼

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 the 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 whether 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, and only displayed when all animation frames cannot be loaded for whatever reason. the "just in case" frame 😭
  • 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. infinite loop era 🔁
  • 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

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 — how many samples each pixel is carrying, 1-4. Most images are out here living their simple life with 1 sample. Planar TIFFs might split the low and high bytes into 2 samples. RGB shows up with 3 samples, and YCbCr plus RGBA are serving 4. 🎨
  • PlanarConfig contiguous|separate — "separate" images split each individual sample or component (f.ex. R and G and B, bestie, like, individually) into their own planes. "contiguous" mixes the sample bytes one after another. 💫
  • SampleFormat STRING — the pixel sample format, and it's one of these:
  unsigned integer
  signed integer
  floating point
  untyped data
  complex signed int
  complex floating point
  • Tiled BOOL — if it's set, the TIFF is tiled. 🧩
  • Faxpect BOOL — when the "Fax" option was set to "true", and the image genuinely got converted from 1 to 2 bits, this parameter gets set to signal exactly that. It's the little receipt, fr. 📠
  • 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. The different name is there to avoid implicit but impossible compression selection, because tibtiff can decompress many types, but compress only a few. So bestie, read vs write are not the same menu, okay? 🫶

🔄 Load output and save input

  • generic strings — these keys have no specific meanings for Prima, but they're 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 — the GIF comment text 💬
  • delayTime INT — delay in a hundredth of a second between frames. Default: 1
  • disposalMethod INT — the 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 it's set, the GIF image is interlaced. Default: 0
  • left, top INT — frame offset in pixels. Default: 0
  • loopCount INT — how many times 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 it's 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 — (that's the whole note, no extra lore)
  • screenHeight INTEGER — same deal, it's just listed 💀
  • 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 — pick your compression vibe 🎚️
  • delay $milliseconds — the gap between frames
  • 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 — no extra description here, it's just listed, iykyk
  • depth_images — number of depth images available for the frame
  • has_alpha — no extra notes on this one either 🙈
  • 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 — again, just the key, no description
  • 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 — listed, no notes
  • metadata — listed, no notes
  • 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>.

🌈 SEE ALSO 🌈

Prima, Prima::Image, Prima::codecs, Prima::Image::Loader, Prima::Image::Exif, Prima::Image::base64.

And that's the whole page, bestie! 🫶 This lil' doc is living under perl v5.42.0 and was stamped 2024-08-20 — shoutout to the pod::Pr...ge-load(3) page for serving all this info. Go forth and load some images, you absolute icon 💅✨🎀

📦 where this page comes from