# NAME

PDL::IO::Image - Load/save bitmap from/to PDL (via FreeImage library)

# SYNOPSIS

Functional interface:

    use 5.010;
    use PDL;
    use PDL::IO::Image;

    my $pdl1 = rimage('picture.tiff');
    say $pdl1->info;       # PDL: Byte D [400,300] ... width 400, height 300
    # do some hacking with $piddle
    wimage($pdl1, 'output.tiff');
    # you can also use wimage as PDL's method
    $pdl1->wimage('another-output.png');

    my ($pixels, $palette) = rimage('picture-256colors.gif', { palette=>1 });
    say $pixels->info;     # PDL: Byte D [400,300] ... width 400, height 300
    say $palette->info;    # PDL: Byte D [3,256]
    # do some hacking with $pixels and $palette
    wimage($pixels, 'output.gif', { palette=>$palette });

    # load specific image (page) from multi-page file
    my $pdl2 = rimage('picture.tiff', { page=>0 });

    # load specific image + flit vertically before converting to piddle
    my $pdl3 = rimage('picture.tiff', { flip=>'V' });

    # random pixels + ramdom colors (RGBA - 35 bits per pixel)
    (random(400, 300, 4) * 256)->byte->wimage("random.png");

    my $pix1 = (sin(0.25 * rvals(101, 101)) * 128 + 127)->byte;
    say $pix1->info;       # PDL: Byte D [101,101]
    my $pal1 = yvals(3, 256)->byte;
    $pal1->slice("(2),:") .= 0; # set blue part of palette to zero
    say $pal1->info;       # PDL: Byte D [3,256]
    $pix1->wimage("wave1_grayscale.gif"); # default is grayscale palette
    $pix1->wimage("wave2_yellow.gif", { palette=>$pal1 });

    # rotate /rescale before saving
    my $pix2 = (sin(0.25 * xvals(101, 101)) * 128 + 127)->byte;
    $pix2->wimage("wave3_grayscale.gif", { rescale=>[16,16] }); # rescale to 16x16 pixels
    $pix2->wimage("wave4_grayscale.gif", { rescale_pct=>50 }); # rescale to 50%
    $pix2->wimage("wave5_grayscale.gif", { rotate=>33.33 });

Object oriented (OO) interface:

    use 5.010;
    use PDL;
    use PDL::IO::Image;

    # create PDL::IO::Image object from file
    my $pimage1 = PDL::IO::Image->new_from_file('picture.gif');
    say 'width       = ' . $pimage1->get_width;
    say 'height      = ' . $pimage1->get_height;
    say 'image_type  = ' . $pimage1->get_image_type;
    say 'color_type  = ' . $pimage1->get_color_type;
    say 'colors_used = ' . $pimage1->get_colors_used;
    say 'bpp         = ' . $pimage1->get_bpp;
    # you can do some operations with PDL::IO::Image object
    $pimage1->flip_vertical;
    # export pixels from PDL::IO::Image object content into a piddle
    my $pix_pdl = $pimage1->pixels_to_pdl();
    # export palette from PDL::IO::Image object content into a piddle
    my $pal_pdl = $pimage1->palette_to_pdl();

    # let us have a piddle with pixel data
    my $wave_pixels = (sin(0.008 * xvals(2001, 2001)) * 128 + 127)->byte;
    # create PDL::IO::Image object from PDL piddle
    my $pimage2 = PDL::IO::Image->new_from_pdl($wave_pixels);
    # do some transformation with PDL::IO::Image object
    $pimage2->rotate(45);
    $pimage2->rescale(200, 200);
    # export PDL::IO::Image object content into a image file
    $pimage2->save("output.jpg");

# DESCRIPTION

PDL::IO::Image implements I/O for a number of popular image formats. It is based on
["FreeImage library"](http://freeimage.sourceforge.net/) however there is no need to install
FreeImage library on your system because PDL::IO::Image uses [Alien::FreeImage](https://metacpan.org/pod/Alien::FreeImage) module which
handles building FreeImage library from sources (works on Windows, Cygwin, Mac OS X, Linux and other UNIXes).

Check also an excellent FreeImage documentation at [http://freeimage.sourceforge.net/documentation.html](http://freeimage.sourceforge.net/documentation.html)

## Supported file formats

This module supports loading (["new\_from\_file"](#new_from_file) or ["rimage"](#rimage)) and saving (["save"](#save) or ["wimage"](#wimage))
of the following formats (note that not all formats support writing - see `R/W` column).

        BMP  R/W  Windows or OS/2 Bitmap [extensions: bmp]
        ICO  R/W  Windows Icon [extensions: ico]
       JPEG  R/W  JPEG - JFIF Compliant [extensions: jpg,jif,jpeg,jpe]
        JNG  R/W  JPEG Network Graphics [extensions: jng]
      KOALA  R/-  C64 Koala Graphics [extensions: koa]
        IFF  R/-  IFF Interleaved Bitmap [extensions: iff,lbm]
        MNG  R/-  Multiple-image Network Graphics [extensions: mng]
        PBM  R/W  Portable Bitmap (ASCII) [extensions: pbm]
     PBMRAW  R/W  Portable Bitmap (RAW) [extensions: pbm]
        PCD  R/-  Kodak PhotoCD [extensions: pcd]
        PCX  R/-  Zsoft Paintbrush [extensions: pcx]
        PGM  R/W  Portable Greymap (ASCII) [extensions: pgm]
     PGMRAW  R/W  Portable Greymap (RAW) [extensions: pgm]
        PNG  R/W  Portable Network Graphics [extensions: png]
        PPM  R/W  Portable Pixelmap (ASCII) [extensions: ppm]
     PPMRAW  R/W  Portable Pixelmap (RAW) [extensions: ppm]
        RAS  R/-  Sun Raster Image [extensions: ras]
      TARGA  R/W  Truevision Targa [extensions: tga,targa]
       TIFF  R/W  Tagged Image File Format [extensions: tif,tiff]
       WBMP  R/W  Wireless Bitmap [extensions: wap,wbmp,wbm]
        PSD  R/-  Adobe Photoshop [extensions: psd]
        CUT  R/-  Dr. Halo [extensions: cut]
        XBM  R/-  X11 Bitmap Format [extensions: xbm]
        XPM  R/W  X11 Pixmap Format [extensions: xpm]
        DDS  R/-  DirectX Surface [extensions: dds]
        GIF  R/W  Graphics Interchange Format [extensions: gif]
        HDR  R/W  High Dynamic Range Image [extensions: hdr]
         G3  R/-  Raw fax format CCITT G.3 [extensions: g3]
        SGI  R/-  SGI Image Format [extensions: sgi,rgb,rgba,bw]
        EXR  R/W  ILM OpenEXR [extensions: exr]
        J2K  R/W  JPEG-2000 codestream [extensions: j2k,j2c]
        JP2  R/W  JPEG-2000 File Format [extensions: jp2]
        PFM  R/W  Portable floatmap [extensions: pfm]
       PICT  R/-  Macintosh PICT [extensions: pct,pict,pic]
        RAW  R/-  RAW camera image [extensions: 3fr,arw,bay,bmq,cap,cine,
                      cr2,crw,cs1,dc2, dcr,drf,dsc,dng,erf,fff,ia,iiq,k25,
                      kc2,kdc,mdc,mef,mos,mrw,nef,nrw,orf,pef, ptx,pxn,qtk,
                      raf,raw,rdc,rw2,rwl,rwz,sr2,srf,srw,sti]
       WEBP  R/W  Google WebP image format [extensions: webp]
    JPEG-XR  R/W  JPEG XR image format [extensions: jxr,wdp,hdp]

**IMPORTANT** the strings in the first column (e.g. `'BMP'`, `'JPEG'`, `'PNG'`) are used as a format identifier in
["new\_from\_file"](#new_from_file), ["save"](#save), ["rimage"](#rimage), ["wimage"](#wimage) (+some other methods).

The supported format may differ depending on FreeImage library version. You can list what exactly you FreeImage library
can handle like this:

    for (PDL::IO::Image->format_list) {
      my $r = PDL::IO::Image->format_can_read($_) ? 'R' : '-';
      my $w = PDL::IO::Image->format_can_write($_) ? 'W' : '-';
      my $e = PDL::IO::Image->format_extension_list($_);
      my $d = PDL::IO::Image->format_description($_);
      printf("% 7s  %s/%s  %s [extensions: %s]\n", $_, $r, $w, $d, $e);
    }

## Supported image types

This module can handle the following image types.

    BITMAP   Standard image: 1-, 4-, 8-, 16-, 24-, 32-bit
    UINT16   Array of unsigned short: unsigned 16-bit
    INT16    Array of short: signed 16-bit
    UINT32   Array of unsigned long: unsigned 32-bit
    INT32    Array of long: signed 32-bit
    FLOAT    Array of float: 32-bit IEEE floating point
    DOUBLE   Array of double: 64-bit IEEE floating point
    RGB16    48-bit RGB image: 3 x 16-bit
    RGBA16   64-bit RGBA image: 4 x 16-bit
    RGBF     96-bit RGB float image: 3 x 32-bit IEEE floating point
    RGBAF    128-bit RGBA float image: 4 x 32-bit IEEE floating point

Currently **NOT SUPPORTED**:

    COMPLEX  Array of FICOMPLEX: 2 x 64-bit IEEE floating point

Image type is important especially when you want to load image data from PDL piddle into a PDL::IO::Image object
(and later save to a file). Based on piddle size and piddle type the image type is detected (in ["new\_from\_pdl"](#new_from_pdl)
and ["wimage"](#wimage)).

    W .. image width
    H .. image height
    PDL Byte     [W,H]       BITMAP 1-/4-/8-bits per pixel
    PDL Byte     [W,H,3]     BITMAP 24-bits per pixel (RGB)
    PDL Byte     [W,H,4]     BITMAP 32-bits per pixel (RGBA)
    PDL Ushort   [W,H]       UINT16
    PDL Short    [W,H]       INT16
    PDL LongLong [W,H]       UINT32 (unfortunately there is no PDL Ulong type)
    PDL Long     [W,H]       INT32
    PDL Float    [W,H]       FLOAT
    PDL Double   [W,H]       DOUBLE
    PDL Ushort   [W,H,3]     RGB16
    PDL Ushort   [W,H,4]     RGBA16
    PDL Float    [W,H,3]     RGBf
    PDL Float    [W,H,4]     RGBAF

**IMPORTANT** the strings with type name (e.g. `'BITMAP'`, `'UINT16'`, `'RGBAF'`) are used as a image type
identifier in method ["convert\_image\_type"](#convert_image_type) and a return value of method ["get\_image\_type"](#get_image_type).

Not all file formats support all image formats above (especially those non-BITMAP image types). If you are in doubts use
`tiff` format for storing unusual image types.

# FUNCTIONS

The functional interface comprises of two functions ["rimage"](#rimage) and ["wimage"](#wimage) - both are exported by default.

## rimage

Loads image into a PDL piddle (or into two piddles in case of palette-based images).

    my $pixels_pdl = rimage($filename);
    #or
    my $pixels_pdl = rimage($filename, \%options);
    #or
    my ($pixels_pdl, $palette_pdl) = rimage($filename, { palette=>1 });

Internally it works in these steps:

- Create PDL::IO::Image object from the input file.
- Do optional transformations (based on `%options`) with PDL::IO::Image object.
- Export PDL::IO::Image object into a piddle(s) via ["pixels\_to\_pdl"](#pixels_to_pdl) and ["palette\_to\_pdl"](#palette_to_pdl).
- **IMPORTANT:** ["rimage"](#rimage) returns piddle(s) not a PDL::IO::Image object

Items supported in **options** hash:

- format

    String identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)), default
    is `'AUTO'` which means that format is auto detected.

- format\_flag

    Optional flag related to loading given file format - see ["new\_from\_file"](#new_from_file) method for more info.

- page

    Index (0-based) of a specific page to load from multi-page images (TIFF, ICO or animated GIF).

- flip

    Values `'H'`, `'V'` or `'HV'` specifying horizontal, vertical or horizontal+vertical flipping.
    Default: do not flip.

- rotate

    Optional floating point value with rotation angle (in degrees) - see ["rotate"](#rotate) method for more info.
    Default: do not rotate.

- convert\_image\_type

    String identifying image type (e.g. `'BITMAP'` - for valid values see ["Supported image types"](#supported-image-types)).
    Default: no conversion.

- region

    An arrayref with a region specification like `[$x1,$x2,$y1,$y2]` - see ["pixels\_to\_pdl"](#pixels_to_pdl) method for more info.
    Default: create the output piddle from the whole image.

- palette

    Values `0` (default) or `1` - whether to load (or not) color lookup table (aka LUT).

## wimage

Write PDL piddle(s) into a image file.

    $pixels_pdl->wimage($filename);
    #or
    $pixels_pdl->wimage($filename, \%options);

    wimage($pixels_pdl, $filename);
    #or
    wimage($pixels_pdl, $filename, \%options);

Internally it works in these steps:

- Create PDL::IO::Image object from the `$pixels_piddle` (+ `$palette_piddle` passed as `palette` option).
- Dimensions and type of `$pixels_piddle` must comply with ["Supported image types"](#supported-image-types).
- Do optional transformations (based on `%options`) with PDL::IO::Image object.
- Export PDL::IO::Image object into a image file via ["save"](#save) method.

Items supported in **options** hash:

- format

    String identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)), default
    is `'AUTO'` which means that format is auto detected from extension of `$filename`.

- format\_flag

    Optional flag related to saving given file format - see ["save"](#save) method for more info.

- palette

    Optional PDL piddle with color palette (has to be `PDL Byte[3,N]` where 0 < N <= 256) containing RGB triplets.

- flip

    Values `'H'`, `'V'` or `'HV'` specifying horizontal, vertical or horizontal+vertical flipping.
    Default: do not flip.

- rotate

    Optional floating point value with rotation angle (in degrees) - see ["rotate"](#rotate) method for more info.
    Default: do not rotate.

- rescale

    Optional arrayref with rescale specification (in pixels) e.g. `[$new_w, $new_h]` - see ["rescale"](#rescale) method for more info.
    Default: do not rescale.

- rescale\_pct

    Optional floating point value with rescale ratio in percent - see ["rescale\_pct"](#rescale_pct) method for more info.
    Default: do not rescale.

- convert\_image\_type

    String identifying image type (e.g. `'BITMAP'` - for valid values see ["Supported image types"](#supported-image-types)).
    Default: no conversion.

# METHODS

## new\_from\_file

Create PDL::IO::Image object from image file.

    my $pimage = IO::PDL::Image->new_from_file($filename);
    #or
    my $pimage = IO::PDL::Image->new_from_file($filename, $format);
    #or
    my $pimage = IO::PDL::Image->new_from_file($filename, $format, $format_flag);
    #or
    my $pimage = IO::PDL::Image->new_from_file($filename, $format, $format_flag, $page);

    #if you have image file content in a scalar variable you can use
    my $pimage = IO::PDL::Image->new_from_file(\$variable_with_image_data);

`$filename` - input image file name or a reference to scalar variable with imiga data.

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)),
default is `'AUTO'` which means that format is auto detected (based on file header with fall-back to detection based
on file extension).

`$format_flag` - optional flag related to loading given file format, default if `0` (no extra flags). The flag can be
created by OR-ing some of available constants:

    PDL::IO::Image::GIF_LOAD256        Load the image as a 256 color image with unused
                                       palette entries, if it's 16 or 2 color
    PDL::IO::Image::GIF_PLAYBACK       'Play' the GIF to generate each frame (as 32bpp)
                                       instead of returning raw frame data when loading
    PDL::IO::Image::ICO_MAKEALPHA      Convert to 32-bit and create an alpha channel from
                                       the ANDmask when loading
    PDL::IO::Image::JPEG_FAST          Load the file as fast as possible, sacrificing some quality
    PDL::IO::Image::JPEG_ACCURATE      Load the file with the best quality, sacrificing some speed
    PDL::IO::Image::JPEG_CMYK          This flag will load CMYK bitmaps as 32-bit separated CMYK
    PDL::IO::Image::JPEG_GREYSCALE     Load and convert to a 8-bit greyscale image (faster than
                                       loading as 24-bit and converting to 8-bit)
    PDL::IO::Image::JPEG_EXIFROTATE    Load and rotate according to Exif 'Orientation' tag if available
    PDL::IO::Image::PCD_BASE           This flag will load the one sized 768 x 512
    PDL::IO::Image::PCD_BASEDIV4       This flag will load the bitmap sized 384 x 256
    PDL::IO::Image::PCD_BASEDIV16      This flag will load the bitmap sized 192 x 128
    PDL::IO::Image::PNG_IGNOREGAMMA    Avoid gamma correction on loading
    PDL::IO::Image::PSD_CMYK           Reads tags for separated CMYK (default is conversion to RGB)
    PDL::IO::Image::PSD_LAB            Reads tags for CIELab (default is conversion to RGB)
    PDL::IO::Image::RAW_PREVIEW        Try to load the embedded JPEG preview with included Exif
                                       data or default to RGB 24-bit
    PDL::IO::Image::RAW_DISPLAY        Load the file as RGB 24-bit
    PDL::IO::Image::RAW_HALFSIZE       Output a half-size color image
    PDL::IO::Image::TARGA_LOAD_RGB888  If set the loader converts RGB555 and ARGB8888 -> RGB888
    PDL::IO::Image::TIFF_CMYK          Load CMYK bitmaps as separated CMYK (default is conversion to RGB)

## new\_from\_pdl

Create PDL::IO::Image object from PDL piddle with pixel (+ optional palette) data.

    my $pimage = IO::PDL::Image->new_from_pdl($pixels_pdl);
    #or
    my $pimage = IO::PDL::Image->new_from_pdl($pixels_pdl, $palette_pdl);

`$pixels_pdl` - PDL piddle containing pixel data, dimensions and type must comply with ["Supported image types"](#supported-image-types).

`$palette_pdl` - Optional PDL piddle with color palette (has to be `PDL Byte[3,N]` where 0 < N <= 256) containing RGB triplets.

## clone

Create a copy (clone) of PDL::IO::Image object.

    my $pimage_copy = $pimage->clone();

## pixels\_to\_pdl

Export pixel data from PDL::IO::Image object into a piddle.

    my $pixels_pdl = $pimage->pixels_to_pdl;
    #or
    my $pixels_pdl = $pimage->pixels_to_pdl($x1, $x2, $y1, $y2);

`$x1, $x2, $y1, $y2` - Optional specification of image sub-region to be exported. All values are 0-based, negative
values can be used to specify boundary "from the end".

## palette\_to\_pdl

Export palette (aka LUT - color lookup table) data from PDL::IO::Image object into a piddle.

    my $palette_pdl = $pimage->palette_to_pdl;

The output piddle is ususally `PDL Byte [3, 256]`. Returns `undef` if image represented by `$pimage` does not use
palette.

## save

Export PDL::IO::Image object into a image file.

    $pimage->save($filename, $format, $flags);
    #or
    $pimage->save($filename, $format);
    #or
    $pimage->save($filename);

    #you can save the image data to a variable like this
    my $output_image;
    $pimage->save(\$output_image, $format);
    #NOTE: $format is mandatory in this case

Returns `$pimage` (self).

`$filename` - output image file name or a reference to perl scalar variable.

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)),
default is `'AUTO'` which means that format is auto detected from extension of `$filename`.

`$format_flag` - optional flag related to saving given file format, default if `0` (no extra flags). The flag can be
created by OR-ing some of available constants:

    PDL::IO::Image::BMP_SAVE_RLE              Compress the bitmap using RLE when saving
    PDL::IO::Image::EXR_FLOAT                 Save data as float instead of as half (not recommended)
    PDL::IO::Image::EXR_NONE                  Save with no compression
    PDL::IO::Image::EXR_ZIP                   Save with zlib compression, in blocks of 16 scan lines
    PDL::IO::Image::EXR_PIZ                   Save with piz-based wavelet compression
    PDL::IO::Image::EXR_PXR24                 Save with lossy 24-bit float compression
    PDL::IO::Image::EXR_B44                   Save with lossy 44% float compression
    PDL::IO::Image::EXR_LC                    Save with one luminance and two chroma channels, rather than RGB (lossy)
      for J2K format: integer X in [1..512]   Save with a X:1 rate (default = 16)
      for JP2 format: integer X in [1..512]   Save with a X:1 rate (default = 16)
    PDL::IO::Image::JPEG_QUALITYSUPERB        Saves with superb quality (100:1)
    PDL::IO::Image::JPEG_QUALITYGOOD          Saves with good quality (75:1 - default)
    PDL::IO::Image::JPEG_QUALITYNORMAL        Saves with normal quality (50:1)
    PDL::IO::Image::JPEG_QUALITYAVERAGE       Saves with average quality (25:1)
    PDL::IO::Image::JPEG_QUALITYBAD           Saves with bad quality (10:1)
      for JPEG format: integer X in [0..100]  Save with quality X:1
    PDL::IO::Image::JPEG_PROGRESSIVE          Saves as a progressive JPEG file
    PDL::IO::Image::JPEG_SUBSAMPLING_411      Save with high 4x1 chroma subsampling (4:1:1)
    PDL::IO::Image::JPEG_SUBSAMPLING_420      Save with medium 2x2 chroma subsampling (4:2:0) - default value
    PDL::IO::Image::JPEG_SUBSAMPLING_422      Save with low 2x1 chroma subsampling (4:2:2)
    PDL::IO::Image::JPEG_SUBSAMPLING_444      Save with no chroma subsampling (4:4:4)
    PDL::IO::Image::JPEG_OPTIMIZE             On saving, compute optimal Huffman coding tables
    PDL::IO::Image::JPEG_BASELINE             Save basic JPEG, without metadata or any markers
      for JXR format: integer X in [1..100)   Save with quality X:1 (default = 80), using X=100 means lossless
    PDL::IO::Image::JXR_LOSSLESS              Save lossless (quality = 100)
    PDL::IO::Image::JXR_PROGRESSIVE           Saves as a progressive JPEG-XR file
    PDL::IO::Image::PNG_Z_BEST_SPEED          Save using ZLib level 1 compression (default value is 6)
    PDL::IO::Image::PNG_Z_DEFAULT_COMPRESSION Save using ZLib level 6 compression (default)
    PDL::IO::Image::PNG_Z_BEST_COMPRESSION    Save using ZLib level 9 compression (default value is 6)
    PDL::IO::Image::PNG_Z_NO_COMPRESSION      Save without ZLib compression
    PDL::IO::Image::PNG_INTERLACED            Save using Adam7 interlacing
    PDL::IO::Image::PNM_SAVE_RAW              Saves the bitmap as a binary file
    PDL::IO::Image::PNM_SAVE_ASCII            Saves the bitmap as an ASCII file
    PDL::IO::Image::TIFF_CMYK                 Stores tags for separated CMYK
    PDL::IO::Image::TIFF_PACKBITS             Save using PACKBITS compression
    PDL::IO::Image::TIFF_DEFLATE              Save using DEFLATE compression (also known as ZLIB compression)
    PDL::IO::Image::TIFF_ADOBE_DEFLATE        Save using ADOBE DEFLATE compression
    PDL::IO::Image::TIFF_NONE                 Save without any compression
    PDL::IO::Image::TIFF_CCITTFAX3            Save using CCITT Group 3 fax encoding
    PDL::IO::Image::TIFF_CCITTFAX4            Save using CCITT Group 4 fax encoding
    PDL::IO::Image::TIFF_LZW                  Save using LZW compression
    PDL::IO::Image::TIFF_JPEG                 Save using JPEG compression (8-bit greyscale and 24-bit only)
    PDL::IO::Image::TIFF_LOGLUV               Save using LogLuv compression (only available with RGBF images
    PDL::IO::Image::TARGA_SAVE_RLE            Save with RLE compression

## dump\_bitmap

Extract raw bitmap data (+ do necessary image type and/or bpp conversions).

    my ($width, $height, $bpp, $pixels, $palette) = $pimage->dump_bitmap;
    #or
    my ($width, $height, $bpp, $pixels, $palette) = $pimage->dump_bitmap($required_bpp);

`$pixels` and `$palette` are raw data buffers containg sequence of RGB (RGBA) byte values.

`$required_bpp` can be 8, 24 or 32 - before dumping the image is converted to `BITMAP` image type + colors depth is
converted to given value. Default is autodetect the lowest sufficient bpp (from 8, 24, 32).

## get\_image\_type

Returns the data type of a bitmap (e.g. `'BITMAP'`, `'UINT16'`) - see ["Supported image types"](#supported-image-types).

    my $imtype = $pimage->get_image_type;

## get\_colors\_used

Returns the palette size for palletised bitmaps (usually 256), and 0 for high-colour bitmaps.

    my $colors = $pimage->get_colors_used;

## get\_bpp

Returns the size of one pixel in the bitmap in bits (aka bits per pixel).

    my $bpp = $pimage->get_bpp;

## get\_width

Returns the width of the bitmap in pixels.

    my $w = $pimage->get_width;

## get\_height

Returns the height of the bitmap in pixels.

    my $h = $pimage->get_height;

## get\_dots\_per\_meter\_x

Returns the horizontal resolution, in pixels-per-meter.

    my $dpmx = $pimage->get_dots_per_meter_x;

## set\_dots\_per\_meter\_x

Set the horizontal resolution, in pixels-per-meter.

    $pimage->set_dots_per_meter_x($res);

Returns `$pimage` (self).

## get\_dots\_per\_meter\_y

Returns the vertical resolution, in pixels-per-meter.

    my $dpmy = $pimage->get_dots_per_meter_y;

## set\_dots\_per\_meter\_y

Set the vertical resolution, in pixels-per-meter.

    $pimage->set_dots_per_meter_y($res);

Returns `$pimage` (self).

## get\_color\_type

Returns color type.

    my $coltype = $pimage->get_color_type;

The return value is a string:

    'MINISBLACK'   Monochrome bitmap (1-bit): first palette entry is black.
                   Palletised bitmap (4 or 8-bit) and single channel non standard bitmap: greyscale palette
    'MINISWHITE'   Monochrome bitmap (1-bit): first palette entry is white.
                   Palletised bitmap (4 or 8-bit): inverted greyscale palette
    'PALETTE'      Palettized bitmap (1, 4 or 8 bit)
    'RGB'          High-color bitmap (16, 24 or 32 bit), RGB16 or RGBF
    'RGBALPHA'     High-color bitmap with an alpha channel (32 bit bitmap, RGBA16 or RGBAF)
    'CMYK'         CMYK bitmap (32 bit only)

## is\_transparent

Returns `1` when the transparency table is enabled (1-, 4- or 8-bit images) or when the
input dib contains alpha values (32-bit images, RGBA16 or RGBAF images). Returns `0` otherwise.

    my $bool = $pimage->is_transparent;

## get\_transparent\_index

Returns the palette entry used as transparent color for the image specified. Works for
palletised images only and returns -1 for high color images or if the image has no color set to
be transparent.

    my $idx = $pimage->get_transparent_index;

## set\_transparent\_index

Sets the index of the palette entry to be used as transparent color for the image specified.
Does nothing on high color images.

    $pimage->set_transparent_index($index);

Returns `$pimage` (self).

## flip\_horizontal

Flip the image horizontally along the vertical axis.

    $pimage->flip_horizontal;

Returns `$pimage` (self).

## flip\_vertical

Flip the image vertically along the horizontal axis.

    $pimage->flip_vertical;

Returns `$pimage` (self).

## rotate

Rotates image, the angle of counter clockwise rotation is specified by the `$angle` parameter in degrees.

    $pimage->rotate($angle);
    #or
    $pimage->rotate($angle, $bg_r, $bg_g, $bg_b, $bg_a);   # RGBA(F|16) images
    $pimage->rotate($angle, $bg_r, $bg_g, $bg_b);          # RGB(F|16) images
    $pimage->rotate($angle, $bg);                          # palette-based images

You can specify optional backgroung color via `$bg_r`, `$bg_g`, `$bg_b`, `$bg_a` or `$bg`.

Returns `$pimage` (self).

## rescale

Performs resampling (scaling/zooming) of a greyscale or RGB(A) image to the desired destination width and height.

    $pimage->rescale($dst_width, $dst_height, $filter);
    #or
    $pimage->rescale($dst_width, 0);  # destination height is computed
    #or
    $pimage->rescale(0, $dst_height); # destination width is computed

Returns `$pimage` (self).

`$filter` - resampling filter identifier:

    0 .. Box, pulse, Fourier window, 1st order (constant) b-spline
    1 .. Mitchell & Netravali's two-param cubic filter
    2 .. Bilinear filter
    3 .. 4th order (cubic) b-spline
    4 .. Catmull-Rom spline, Overhauser spline
    5 .. Lanczos3 filter

## rescale\_pct

Performs resampling by given percentage ratio.

    $pimage->rescale($dst_width_pct, $dst_height_pct, $filter);
    #or
    $pimage->rescale($dst_pct);

Returns `$pimage` (self).

`$filter` - see ["rescale"](#rescale)

## convert\_image\_type

Converts an image to destination `$image_type`.

    $pimage->convert_image_type($image_type, $scale_linear);
    #or
    $pimage->convert_image_type($image_type);

Returns `$pimage` (self).

`$image_type` - string identifying image type (e.g. `'BITMAP'`, `'UINT16'` - for valid values see ["Supported image types"](#supported-image-types)).

## adjust\_colors

Adjusts an image's brightness, contrast and gamma as well as it may optionally invert the image within a single operation.

    $pimage->adjust_colors($brightness, $contrast, $gamma, $invert);

Returns `$pimage` (self).

`$brightness` - real value from range `[-100..100]`, value `0` means no change, less than 0 will make the
image darker and greater than 0 will make the image brighter

`$contrast` - real value from range `[-100..100]`, value `0` means no change, less than 0 will decrease the
contrast and greater than 0 will increase the contrast of the image

`$gamma` - real value greater than 0, value of 1.0 leaves the image alone, less than one
darkens it, and greater than one lightens it

`$invert` - `0` or `1` invert (or not) all pixels

## color\_to\_4bpp

Converts a bitmap to 4 bits. If the bitmap was a high-color bitmap (16, 24 or 32-bit) or if it was
a monochrome or greyscale bitmap (1 or 8-bit), the end result will be a greyscale bitmap,
otherwise (1-bit palletised bitmaps) it will be a palletised bitmap.

    $pimage->color_to_4bpp();

Returns `$pimage` (self).

## color\_to\_8bpp

Converts a bitmap to 8 bits. If the bitmap was a high-color bitmap (16, 24 or 32-bit) or if it was
a monochrome or greyscale bitmap (1 or 4-bit), the end result will be a greyscale bitmap,
otherwise (1 or 4-bit palletised bitmaps) it will be a palletised bitmap.

    $pimage->color_to_8bpp();

Returns `$pimage` (self).

## color\_to\_8bpp\_grey

Converts a bitmap to a 8-bit greyscale image with a linear ramp. Contrary to the
FreeImage\_ConvertTo8Bits function, 1-, 4- and 8-bit palletised images are correctly
converted, as well as images with a FIC\_MINISWHITE color type.

    $pimage->color_to_8bpp_grey();

Returns `$pimage` (self).

## color\_to\_16bpp\_555

Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 5 bits green
and 5 bits blue. One bit in each pixel is unused.

    $pimage->color_to_16bpp_555();

Returns `$pimage` (self).

## color\_to\_16bpp\_565

Converts a bitmap to 16 bits, where each pixel has a color pattern of 5 bits red, 6 bits green
and 5 bits blue.

    $pimage->color_to_16bpp_565();

Returns `$pimage` (self).

## color\_to\_24bpp

Converts a bitmap to 24 bits per pixel.

    $pimage->color_to_24bpp();

Returns `$pimage` (self).

## color\_to\_32bpp

Converts a bitmap to 32 bits per pixel.

    $pimage->color_to_32bpp();

Returns `$pimage` (self).

## color\_dither

Converts a bitmap to 1-bit monochrome bitmap using a dithering algorithm.

    $pimage->color_dither($algorithm);
    #or
    $pimage->color_dither();

Returns `$pimage` (self).

Possible `$algorithm` values:

    0 .. Floyd & Steinberg error diffusion (DEFAULT)
    1 .. Bayer ordered dispersed dot dithering (order 2 dithering matrix)
    2 .. Bayer ordered dispersed dot dithering (order 3 dithering matrix)
    3 .. Ordered clustered dot dithering (order 3 - 6x6 matrix)
    4 .. Ordered clustered dot dithering (order 4 - 8x8 matrix)
    5 .. Ordered clustered dot dithering (order 8 - 16x16 matrix)
    6 .. Bayer ordered dispersed dot dithering (order 4 dithering matrix)

## color\_threshhold

Converts a bitmap to 1-bit monochrome bitmap using a `$threshold` between \[0..255\] (default is 127).

    $pimage->color_threshhold($threshold);
    #or
    $pimage->color_threshhold();

Returns `$pimage` (self).

## color\_quantize

    $pimage->color_quantize($quantize);
    #or
    $pimage->color_quantize();

Returns `$pimage` (self).

Possible `$quantize` values:

    0 .. Xiaolin Wu color quantization algorithm
    1 .. NeuQuant neural-net quantization algorithm by Anthony Dekker

## tone\_mapping

Converts a High Dynamic Range image (48-bit RGB or 96-bit RGBF) to a 24-bit RGB image, suitable for display.

    $pimage->tone_mapping($tone_mapping_operator, $param1, $param2);

Returns `$pimage` (self).

`$tone_mapping_operator` - tone mapping operator identifier:

    0 .. Adaptive logarithmic mapping (F. Drago, 2003)
    1 .. Dynamic range reduction inspired by photoreceptor physiology (E. Reinhard, 2005)
    2 .. Gradient domain high dynamic range compression (R. Fattal, 2002)

Optional parameters:

    $pimage->tone_mapping(0, $gamma, $exposure);
    #or
    $pimage->tone_mapping(1, $intensity, $contrast);
    #or
    $pimage->tone_mapping(2, $color_saturation, $attenuation);

## free\_image\_version

Returns a string containing the current version of the library.

    my $v = PDL::IO::Image->free_image_version();

## format\_list

Returns a list of all supported file formats.

    my @f = PDL::IO::Image->format_list();

## format\_extension\_list

Returns a comma-delimited file extension list for given file format.

    my $ext = PDL::IO::Image->format_extension_list($format);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

## format\_mime\_type

Returns MIME content type string for given file format.

    my $mtype = PDL::IO::Image->format_mime_type($format);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

## format\_description

Returns description string for given file format.

    my $desc = PDL::IO::Image->format_description($format);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

## format\_can\_read

Returns `1` or `0` - module supports (or not) reading given file format.

    my $bool = PDL::IO::Image->format_can_read($format);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

## format\_can\_write

Returns `1` or `0` - module supports (or not) saving given file format.

    my $bool = PDL::IO::Image->format_can_write($format);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

## format\_can\_export\_type

Returns `1` or `0` - module can export (or not) given image type to given file format.

    my $bool = PDL::IO::Image->format_can_export_type($format, $image_type);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

`$image_type` - string identifying image type (e.g. `'BITMAP'` - for valid values see ["Supported image types"](#supported-image-types)).

## format\_can\_export\_bpp

Returns `1` or `0` - module can export (or not) given file format in given bits per pixel depth.

    my $bool = PDL::IO::Image->format_can_export_bpp($format, $bpp);

`$format` - string identifying file format (e.g. `'JPEG'` - for valid values see ["Supported file formats"](#supported-file-formats)).

`$bpp` - bits per pixel (e.g. 1, 4, 8, 16, 24, 32)

## format\_from\_mime

Returns file format string (e.g. `'BMP'`, `'JPEG'` - see ["Supported file formats"](#supported-file-formats)) for given mime type.

    my $format = PDL::IO::Image->format_from_mime($mime_type);

## format\_from\_file

Returns file format string (e.g. `'BMP'`, `'JPEG'` - see ["Supported file formats"](#supported-file-formats)) for given `$filename`.

    my $format = PDL::IO::Image->format_from_file($filename);

# CONSTANTS

There many constants which can be used with ["new\_from\_file"](#new_from_file) or ["save"](#save) methods. These constants are not exported
by this module therefore you have to use full names like this:

    use PDL;
    use PDL::IO::Image;

    my $pimage = PDL::IO::Image->new_from_file("in.jpg", "JPEG", PDL::IO::Image::JPEG_ACCURATE);

# SEE ALSO

[PDL](https://metacpan.org/pod/PDL), [PDL::IO::Pic](https://metacpan.org/pod/PDL::IO::Pic), [PDL::IO::GD](https://metacpan.org/pod/PDL::IO::GD), [Alien::FreeImage](https://metacpan.org/pod/Alien::FreeImage), [http://freeimage.sourceforge.net/](http://freeimage.sourceforge.net/)

# LICENSE

This program is free software; you can redistribute it and/or modify it under the same terms as Perl itself.

# COPYRIGHT

2014+ KMX <kmx@cpan.org>