Ubuntu Manpage: Prima::image-load - Using image subsystem

Provided by: libprima-perl_1.28-1.4_amd64

NAME

       Prima::image-load - Using image subsystem

DESCRIPTION

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

Loading

   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 are:

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

                   loadAll => 1

       index
           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 off.

   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.

Saving

   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 latter.

       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 required.

   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:

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

name
codec full name, string

vendor
codec vendor, string

versionMajor and versionMinor
usually underlying library versions, integers

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

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

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

featuresSupported
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 is.

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.

canLoad
1 if a codec can load images, 0 if not

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

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

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

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

canSaveMultiple
Set if a codec can save more that one frame

canAppend
Set if a codec can append frames to an exising file

types
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.

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

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

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

AUTHOR