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.

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.

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:

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

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.

Chapter 3