Man Linux: Main Page and Category List


       Prima::image-load - Using image subsystem


       Details on image subsystem - image loading, saving, and codec


   Simple loading
       Simplest case, loading a single image would look like:

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

       Image functions can work being either invoked from package, or from
       existing Prima::Image object, in latter case the caller object itself
       is changing. The code above could be also written as

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

       In both cases $x contains image data upon success.  Error is returned
       into $@ variable ( see perldoc perlvar for more info).

   Loading from stream
       "Prima::Image" can also load image 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 call can be also issued in two ways:

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

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

       In second case, the content of the first frame comes to $x and $x[0].
       Sufficient check for error is whether last item of a returned array is
       defined. This check works also if an empty array is returned.  Only
       this last item can be an undefined value, others are guaranteed to be
       valid objects.

       Multiframe syntax is expressed in a set of extra hash keys.  These keys

           Request for loading all frames that can be read from a file.

                   loadAll => 1

           If present, returns a single frame with index given.  Example:

                   index => 8

       map Contains an anonymous array of frame indices to load.  Valid
           indices are above zero, negative ones can’t be counted in a way
           perl array indices are. Example:

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

   Querying extra information
       By default Prima loads image data and palette only. For any other
       information that can be loaded, anonymous hash ’extras’ can be defined.
       To notify a codec that this extra information is desired, loadExtras
       boolean value is used.  Example:

               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 libungif would
       look like:

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

       ’codecID’ is a Prima-defined extra field, which is an index of the
       codec which have loaded the file. This field’s value is useful for
       explicit indication of codec on the save request.

       ’frames’ is also a Prima-defined extra field, with integer value set to
       a number of frames in the image. It might be set to -1, signaling that
       codec is incapable of quick reading of the frame count.  If, however,
       it is necessary to get actual frame count, a ’wantFrames’ profile
       boolean value should be set to 1 - then frames is guaranteed to be set
       to a 0 or positive value, but the request may take longer time,
       especially on a large file with sequential access. Real life example is
       a gif file with more than thousand frames. ’wantFrames’ is useful in
       null load requests.

   Multiprofile loading requests
       The parameters that are accepted by load, are divided into several
       categories - first, those that apply to all loading process and those
       who apply only to a particular frame. Those who are defined by Prima,
       are enumerated above - loadExtras, loadAll etc. Only loadExtras,
       noImageData and iconUnmask are applicable to a frame, other govern the
       loading process. 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 codec documentation;

       The parameters that applicable to any frame, can be specified
       separately to every desirable frame in single call. For that purpose,
       parameter ’profiles’ is defined. ’profiles’ is expected to be an
       anonymous array of hashes, each hash where corresponds to a request
       number. Example:

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

       First hash there applies to frame index 0, second - to frame index 1.
       Note that in code

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

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

   Null load requests
       If it is desired to peek into image, reading type and dimensions only,
       one should set ’noImageData’ boolean value to 1. Using ’noImageData’,
       empty objects with read type are returned, and with extras ’width’ and
       ’height’ set to 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 information about image can be loaded even without frame loading -
       if the codec provides such a functionality. This is the only request
       that cannot be issued on a package:

               $x-> load( $f, map => [], loadExtras => 1);

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

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

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

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

       When loading to an Icon object, the default toolkit action is to build
       the transparency mask based on image data. When it is not the desired
       behavior, e.g., there is no explicit knowledge of image, but the image
       may or may not contain transparency information, "iconUnmask" boolean
       option can be used. When set to a "true" value, and the object is
       "Prima::Icon" descendant, "Prima::Icon::autoMasking" is set to
       "am::None" prior to the file loading. By default this options is turned

   Loading with progress indicator
       Some codecs (PNG,TIFF,JPEG) can notify the caller as they read image
       data.  For this purpose, "Prima::Image" has two events, "onHeaderReady"
       and "onDataReady". If either (or both) are present on image object that
       is issuing load call, and the codec supports progressive loading, these
       events are called.  "onHeaderReady" is called when image header data is
       acquired, and empty image with the dimensions and pixel type is
       allocated. "onDataReady" is called whenever a part of image is ready
       and is loaded in the memory of the object; the position and dimensions
       of the loaded area is reported also. The format of the events is:

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

       "onHeaderReady" is called only once, but "onDataReady" is called as
       soon as new image data is available. To reduce frequency of these
       calls, that otherwise would be issued on every scanline loaded, "load"
       has parameter "eventDelay", a number of seconds, which limits event
       rate. The default "eventDelay" is 0.1 .

       The handling on "onDataReady" must be performed with care. First, the
       image must be accessed read-only, which means no transformations with
       image size and type are allowed. Currently there is no protection for
       such actions ( because codec must perform these ), 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 partial image as it loads. All of
       these share overloading of "onHeaderReady" and "onDataReady". The
       simpler is to call "put_image" from inside "onDataReady":

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

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

               $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 "Prima::ImageViewer" when it is setup
       to monitor image loading progress. See "watch_load_progress" in
       Prima::ImageViewer for details.


   Simple saving
       Typical saving code will be:

          die "$@" unless $x-> save( 'filename.duf');

       Upon a single-frame invocation save returns 1 upon success an 0 on
       failure.  Save requests also can be performed with package syntax:

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

   Saving to a stream
       Saving to a stream requires explicit "codecID" to be supplied. When an
       image is loaded with "loadExtras", this field is always present on the
       image object, and is an integer that selects image encoding 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[0])
             or die "Cannot save:$@";

   Multiframe saving
       In multiframe invocation save returns number of successfully saved
       frames.  File is erased though, if error occurred, 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 object hash reference ’extras’, is
       assumed to be saved as an extra information. It is a codec’s own
       business how it reacts on invalid and/or inacceptable information - but
       typical behavior is that keys that were not recognized by the codec
       just get ignored, and invalid values raise an error.

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

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

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

       Actual correspondence between codecs and their indices is described

       NB - if codecID is not given, codec is selected by the file extension.

   Type conversion
       Codecs usually are incapable of saving images in all formats, so Prima
       either converts an image to an appropriate format or signals an error.
       This behavior is governed by profile key ’autoConvert’, which is 1 by
       default. ’autoConvert’ can be present in image ’extras’ structures.
       With autoConvert set it is guaranteed that image will be saved, but
       original image information may be lost. With autoConvert unset, no
       information will be lost, but Prima may signal an error. Therefore
       general-purpose save routines should be planned carefully. As an
       example the Prima::ImageDialog::SaveImageDialog code might be useful.

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

   Appending frames to an existing file
       This functionality is under design, but the common outlines are already
       set.  Profile key ’append’ ( 0 by default ) triggers this behavior - if
       it is set, then an append attempt is made.

Managing codecs

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

       Codec information that is contained in these hashes is divided into
       following parameters:

           Unique integer value for a codec, same as index of the codec entry
           in results of "Prima::Image->codecs";

           codec full name, string

           codec vendor, string

       versionMajor and versionMinor
           usually underlying library versions, integers

           array of strings, with file extensions that are typical to a codec.
           example: [’tif’, ’tiff’]

           Description of a type of a file, that codec is designed to work
           with.  String.

           Short description of a type of a file, that codec is designed to
           work with.  ( short means 3-4 characters ). String.

           Array of strings, with some features description that a codec
           supports - usually codecs implement only a part of file format
           specification, so it is always interesting to know, what part it

       module and package
           Specify a perl module, usually inside Prima/Image directory into
           Prima distribution, and a package inside the module. The package
           contains some specific functions for work with codec-specific
           parameters. Current implementation defines only ::save_dialog()
           function, that returns a dialog that allows to change these
           parameters. See Prima::ImageDialog::SaveImageDialog for details.
           Strings, undefined if empty.

           1 if a codec can load images, 0 if not

           1 if a codec can load images from streams, 0 otherwise

           1 if a codec can handle multiframe load requests and load frames
           with index more than zero. 0 if not.

           1 if a codec can save images, 0 if not.

           1 if a codec can save images to streams, 0 otherwise

           Set if a codec can save more that one frame

           Set if a codec can append frames to an exising file

           Array of integers - each is a combination of im:: flags, an image
           type, which a codec is capable of saving. First type in list is a
           default one; if image type that to be saved is not in that list,
           the image will be converted to this default type.

           Hash, where keys are those that are accepted by Prima::Image->
           load, and values are default values for these keys.

           Array of strings, each of those is a name of extra information
           entry in ’extras’ hash.

           Hash, where keys are those that are accepted by Prima::Image->
           save, and values are default values for these keys.


       Dmitry Karasik, <>.


       Prima, Prima::Image, Prima::codecs