ImageIO

Description

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

Uses AWT and ImageIO; replaces image task for Java 9+. The task can be used with Java 8 as well, see parameter table for limitations.

Note: this task tries to stay as close as possible to syntax and semantics of image task. However, it uses format attribute rather than encoding attribute, because the latter is a misnomer: almost all tasks use similar attributes for character encodings in files, file names or other strings. Also, when format is not specified, its value is defined by the format of the first processed image file.

Overview of used datatypes
ImageOperation class diagram A diagram of Ant DataType classes used by ImageIO task. org.apache.tools.ant.types.DataType ImageOperation instructions : List addDraw(Draw : instr) addRotate(Rotate : instr) addScale(Scale : instr) The setType() method forces type to one of the values of java.awt.geom.Arc2D: open = Arc2D.OPEN pie = Arc2D.PIE chord = Arc2D.CHORD Parameter is not case-sensitive. BasicShape height : int = 0 width : int = 0 strokeWidth : int = 0 stroke : String = "black" fill : String = "transparent" TransformOperation executeTransformOperation(BufferedImage img) : BufferedImage <<interface>> DrawOperation executeDrawOperation() : BufferedImage The implementing class uses ColorMapper to evaluate the color. Only the values defined in ColorMapper are used. ColorMapper COLOR_BLACK : String = "black" COLOR_BLUE : String = "blue" COLOR_CYAN : String = "cyan" COLOR_DARKGRAY : String = "darkgray" COLOR_GRAY : String = "gray" COLOR_LIGHTGRAY : String = "lightgray" COLOR_DARKGREY : String = "darkgrey" COLOR_GREY : String = "grey" COLOR_LIGHTGREY : String = "lightgrey" COLOR_GREEN : String = "green" COLOR_MAGENTA : String = "magenta" COLOR_ORANGE : String = "orange" COLOR_PINK : String = "pink" COLOR_RED : String = "red" COLOR_WHITE : String = "white" COLOR_YELLOW : String = "yellow" Text string : String = "" font : String = "Arial" point : int = 10 bold : boolean = false color : String = "black" italic : boolean = false Rotate angle : float = 0.0F Scale width : String = "100%" height : String = "100%" keepProportions : boolean = false Draw xloc : int = 0 yloc : int = 0 addText(Text : text) addRectangle(Rectangle rect) addEllipse(Ellipse elip) addArc(Arc arc) Rectangle archeight : int = 0 arcwidth : int = 0 Ellipse Arc start : int = 0 stop : int = 0 type : enumerated = open

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
format Image format.
Valid (case insensitive) are: bmp, gif, jpeg, jpg, png, tif, tiff, wbmp (Java 8 VM lacks support for TIFF, which can be provided by external libraries).		 No; defaults to the format of the (first) original file
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.

The following ImageOperation objects can be specified as nested elements: Rotate, Scale and Draw.

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 (pixels) or a %. No; defaults to 100%
height Sets the height of the image, either as an integer (pixels) 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
Nested elements

Both Text and BasicShape objects can be nested. Currently supported BasicShape objects are Arc, Ellipse and Rectangle.

Common parameters of BasicShape objects
Attribute Description Required
height Height of a BasicShape. No; defaults to 0
width Width of a BasicShape. No; defaults to 0
strokewidth Stroke width of a BasicShape. No; defaults to 0
color Color of a BasicShape. No; defaults to black
fill Fill of a BasicShape. No; defaults to transparent
Parameters specific to Arc objects
Attribute Description Required
start Start angle of an arc in degrees. No; defaults to 0
stop Angle extent of an arc in degrees. No; defaults to 0
type One of chord, open, pie. No; defaults to open
Parameters specific to Ellipse objects

None.

Parameters specific to Rectangle objects
Attribute Description Required
archeight Vertical diameter of the arc at the corners of the rectangle. No; defaults to 0
arcwidth Horisontal diameter of the arc at the corners of the rectangle. No; defaults to 0
Parameters of Text
Attribute Description Required
string The text string. No; defaults to
font The font to set the text in. No; defaults to Arial
point Size of the font in points. No; defaults to 10
bold Whether the font is bold. No; defaults to false
color Color of the text. No; defaults to black
italic Whether the font is italic. No; defaults to false

mapper

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 160×160 pixel 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 pixels 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>