Image Task

## Image

### Description

Applies a chain of image operations on a set of files.

Requires Java Advanced Image API from Sun.

##### Overview of used datatypes

### Parameters

Attribute | Description | Required
--- | --- | ---
failonerror | Boolean value. If false, note errors to the output but keep going. | No; defaults to true
srcdir | Directory containing the images. | Yes, unless nested fileset is used
encoding | Image encoding type. Valid (case insensitive) are: jpg, jpeg, tif, tiff | No; defaults to jpeg
overwrite | Boolean value. Sets whether or not to overwrite a file if there is naming conflict. | No; defaults to false
gc | Boolean value. Enables garbage collection after each image processed. | No; defaults to false
destdir | Directory where the result images are stored. | No; defaults to value of srcdir
includes | comma- or space-separated list of patterns of files that must be included. | No; defaults to all (**)
includesfile | name of a file. Each line of this file is taken to be an include pattern | No
excludes | comma- or space-separated list of patterns of files that must be excluded. | No; defaults to default excludes or none if defaultexcludes is no
excludesfile | name of a file. Each line of this file is taken to be an exclude pattern | No
defaultexcludes | indicates whether default excludes should be used or not (yes|no). | No; defaults to yes
caseSensitive | Boolean value. Sets case sensitivity of the file system. | No; defaults to false
followSymlinks | Boolean value. Sets whether or not symbolic links should be followed. | No; defaults to true

### Parameters specified as nested elements

This task forms an implicit FileSet and supports most attributes of `<fileset>` as well as the nested `<include>`, `<exclude>` and `<patternset>` elements.

#### ImageOperation

Adds an ImageOperation to chain.

##### Nested elements

ImageOperation can handle nested `Rotate`, `Draw`, `Rectangle`, `Text` and `Scale` objects.

#### Rotate

Adds a Rotate ImageOperation to chain.

##### Parameters

Attribute | Description | Required
--- | --- | ---
angle | Float value. Sets the angle of rotation in degrees. | No; defaults to 0.0F

#### Scale

Adds a Scale ImageOperation to chain.

##### Parameters

Attribute | Description | Required
--- | --- | ---
proportions | Sets which dimension to control proportions from. Valid values are: ignore— treat the dimensions independently. height—keep proportions based on the width. width—keep proportions based on the height. cover—keep proportions and fit in the supplied dimensions. fit—keep proportions and cover the supplied dimensions. | No; defaults to ignore
width | Sets the width of the image, either as an integer or a %. | No; defaults to 100%
height | Sets the height of the image, either as an integer or a %. | No; defaults to 100%

#### Draw

Adds a Draw ImageOperation to chain. DrawOperation DataType objects can be nested inside the Draw object.

##### Parameters

Attribute | Description | Required
--- | --- | ---
xloc | X-Position where to draw nested image elements. | No; defaults to 0
yloc | Y-Position where to draw nested image elements. | No; defaults to 0

#### mapper

Since Apache Ant 1.8.0

You can define filename transformations by using a nested mapper element. The default mapper used by `<image>` is the identity mapper.

You can also use a `filenamemapper` type in place of the `mapper` element.

### Examples

Create thumbnails of my images and make sure they all fit within the 160x160 size whether the image is portrait or landscape.

    <image destdir="samples/low" overwrite="yes">
        <fileset dir="samples/full">
            <include name="**/*.jpg"/>
        </fileset>
        <scale width="160" height="160" proportions="fit"/>
    </image>

Create a thumbnail for all PNG files in `src` of the size of 40 pixel keeping the proportions and store the `src`.

    <image srcdir="src" includes="*.png">
        <scale proportions="width" width="40"/>
    </image>

Same as above but store the result in `dest`.

    <image srcdir="src" destdir="dest" includes="*.png">
        <scale proportions="width" width="40"/>
    </image>

Same as above but store the result to files with original names prefixed by `scaled-`.

    <image srcdir="src" destdir="dest" includes="*.png">
        <scale proportions="width" width="40"/>
        <globmapper from="*" to="scaled-*"/>
    </image>