Contents | Previous | Next Programmer's Guide to the JavaTM 2D API

Chapter    3

Geometries

The Java 2D™ API provides several classes that define common geometric objects, such as points, lines, curves, and rectangles. These new geometry classes are part of the java.awt.geom package. For backward compatibility, the geometry classes that existed in previous versions of the JDK software, such as Rectangle, Point, and Polygon, remain in the java.awt package.

The Java 2D API geometries such as GeneralPath, Arc2D, and Rectangle2D implement the Shape interface defined in java.awt. Shape provides a common protocol for describing and inspecting geometric path objects. A new interface, PathIterator, defines methods for retrieving elements from a geometry.

Using the geometry classes, you can easily define and manipulate virtually any two-dimensional object.

3.1 Interfaces and Classes

The following tables list the key geometry interfaces and classes. Most of these interfaces and classes are part of the java.awt.geom package. Some, like Shape, are part of the java.awt package, primarily to maintain backward compatibility with earlier versions of the JDK software.

Interface
Description
PathIterator
Defines methods for retrieving elements from a path.
Shape
(java.awt)
Provides a common set of methods for describing and inspecting geometric path objects. Implemented by GeneralPath and other geometry classes.

Class
Description
Arc2D
Arc2D.Double
Arc2D.Float
Extends: RectangularShape
Represents an arc defined by a bounding rectangle, start angle, angular extent, and a closure type. Implemented to specify arcs in float and double precision: Arc2D.Float and Arc2D.Double.
Area
Implements: Shape, Cloneable
Represents an area geometry that supports boolean operations.
CubicCurve2D
CubicCurve2D.Double
CubicCurve2D.Float
 
Implements: Shape
Represents a cubic parametric curve segment in (w) coordinate space. Implemented to specify cubic curves in float and double precision: CubicCurve2D.Float and CubicCurve2D.Double.
Dimension2D
Encapsulates a width and height dimension. Abstract superclass for all objects that store a 2D dimension.
Ellipse2D
Ellipse2D.Double
Ellipse2D.Float
Extends: RectangularShape
Represents an ellipse defined by a bounding rectangle. Implemented to specify ellipses in float and double precision: Ellipse2D.Float and Ellipse2D.Double.
FlatteningPathIterator
Returns a flattened view of a PathIterator object.
Can be used to provide flattening behavior for Shapes that don’t perform the interpolation calculations themselves.
GeneralPath
Implements: Shape
Represents a geometric path constructed from lines and quadratic and cubic curves.
Line2D
Line2D.Double
Line2D.Float
Implements: Shape
Represents a line segment in (x, y) coordinate space. Implemented to specify lines in float and double precision: Line2D.Float and Line2D.Double.
Point2D
Point2D.Double
Point2D.Float
A point representing a location in (x,y) coordinate space. Implemented to specify points in float and double precision: Point2D.Float and Point2D.Double.
QuadCurve2D
QuadCurve2D.Double
QuadCurve2D.Float
Implements: Shape
Represents a quadratic parametric curve segment in (x, y) coordinate space. Implemented to specify quadratic curves in float and double precision: QuadCurve2D.Float and QuadCurve2D.Double.
Rectangle2D
Rectangle2D.Double
Rectangle2D.Float
Extends: RectangularShape
Represents a rectangle defined by a location (x, y) and dimension (w x h). Implemented to specify rectangles in float and double precision: Rectangle2D.Float and Rectangle2D.Double.
RectangularShape
Implements: Shape
Provides common manipulation routines for operating on shapes that have rectangular bounds.
RoundRectangle2D
RoundRectangle2D.Double
RoundRectangle2D.Float
Extends: RectangularShape
Represents a rectangle with rounded corners defined by a location (x, y), a dimension (w x h), and the width and height of the corner arc. Implemented to specify round rectangles in float and double precision: RoundRectangle2D.Float and RoundRectangle2D.Double.

3.2 Geometry Concepts

A Shape is an instance of any class that implements the Shape interface, such as GeneralPath or Rectangle2D.Float. A Shape’s contour (outline) is referred to as its path.

When a Shape is drawn, the pen style defined by the Stroke object in the Graphics2D context is applied to the Shape’s path. When a Shape is filled, the Paint in the Graphics2D context is applied to the area within its path. For more information, see “Rendering with Graphics2D” on page 15.

A Shape’s path can be also used to define a clipping path. A clipping path determines what pixels are rendered—only those pixels that lie within the area defined by the clipping path are rendered. The clipping path is part of the Graphics2D context. For more information, see “Setting the Clipping Path” on page 32.

A GeneralPath is a shape that can be used to represent any two-dimensional object that can be constructed from lines and quadratic or cubic curves. For convenience, java.awt.geom provides additional implementations of the Shape interface that represent common geometric objects such as rectangles, ellipses, arcs, and curves. The Java2D™ API also provides a special type of shape that supports constructive area geometry.

3.2.1 Constructive Area Geometry

Constructive Area Geometry (CAG) is the process of creating new geometric objects by performing boolean operations on existing objects. In the Java 2D API, a special type of Shape called an Area supports boolean operations. You can construct an Area from any Shape.

Areas support the following Boolean operations:

These operations are illustrated in Figure 3-1.

Graphic illustration of union, intersection, subtraction and exclusive OR boolean operations

Figure 3-1 Boolean Operations

3.2.2 Bounds and Hit Testing

A bounding box is a rectangle that fully encloses a shape’s geometry. Bounding boxes are used to determine whether or not an object has been selected or “hit” by the user.

The Shape interface defines two methods for retrieving a shape’s bounding box, getBounds and getBounds2D. The getBounds2D method returns a Rectangle2D instead of a Rectangle, providing a higher-precision description of the shape’s bounding box.

Shape also provides methods for determining whether or not:

3.3 Combining Areas to Create New Shapes

Areas can be used to quickly construct complex Shapes from simple shapes such as circles and squares. To create a new complex Shape by combining Areas:

  1. Using Shapes, construct the Areas to be combined.
  2. Call the appropriate Boolean operators: add, subtract, intersect, exclusiveOr.

For example, CAG could be used to create a pear like that shown in Figure 3-2.

The following context describes the graphic

Figure 3-2 Pear constructed from circles

The body of the pear is constructed by performing a union operation on two overlapping Areas: a circle and an oval. The leaves are each created by performing an intersection on two overlapping circles and then joined into a single Shape through a union operation. Overlapping circles are also used to construct the stem through two subtraction operations.

3.4 Creating a Custom Shape

You can implement the Shape interface to create a class that defines a new type of shape. It doesn’t matter how you represent the shape internally, as long as you can implement the Shape interface methods. The Shape must be able to generate a path that specifies its contour.

For example, you could create a simple implementation of Shape that represents polygons as arrays of points. Once the polygon is built, it could be passed to draw, setClip, or any other method that expects a Shape object as an argument.

The PolygonPath class must implement the Shape interface methods:

 


Contents | Previous | Next Programmer's Guide to the JavaTM 2D API
JavaTM 2 SDK, Standard Edition, 1.4 version