Docjar: A Java Source and Docuemnt Enginecom.*    java.*    javax.*    org.*    all    new    plug-in

Quick Search    Search Deep

java.awt.geom
Class Area  view Area download Area.java

java.lang.Object
  extended byjava.awt.geom.Area
All Implemented Interfaces:
java.lang.Cloneable, java.awt.Shape

public class Area
extends java.lang.Object
implements java.awt.Shape, java.lang.Cloneable

The Area class represents any area for the purpose of Constructive Area Geometry (CAG) manipulations. CAG manipulations work as an area-wise form of boolean logic, where the basic operations are:

  • Add (in boolean algebra: A or B)
  • Subtract (in boolean algebra: A and (not B) )
  • Intersect (in boolean algebra: A and B)
  • Exclusive Or
    Illustration of CAG operations
    Above is an illustration of the CAG operations on two ring shapes.

    The contains and intersects() methods are also more accurate than the specification of #Shape requires.

    Please note that constructing an Area can be slow (Self-intersection resolving is proportional to the square of the number of segments).

    Since:
    1.2

    Nested Class Summary
    private  class Area.AreaIterator
              Private pathiterator object.
    private  class Area.CubicSegment
              Cubic Bezier curve segment
    private  class Area.Intersection
              A small wrapper class to store intersection points
    private  class Area.LineSegment
               
    private  class Area.QuadSegment
              Quadratic Bezier curve segment Note: Most peers don't support quadratics directly, so it might make sense to represent them as cubics internally and just be done with it.
    private  class Area.Segment
              Class representing a linked-list of vertices forming a closed polygon, convex or concave, without holes.
     
    Field Summary
    private  java.util.Vector cc_intersections
              Vector (temporary) storing curve-curve intersections
    private static double EPSILON
              General numerical precision
    (package private)  java.util.Vector holes
              Segment vectors containing solid areas and holes This is package-private to avoid an accessor method.
    private static double PE_EPSILON
              Snap distance - points within this distance are considered equal
    private static double RS_EPSILON
              recursive subdivision epsilon - (see getRecursionDepth)
    (package private)  java.util.Vector solids
              Segment vectors containing solid areas and holes This is package-private to avoid an accessor method.
    private  int windingRule
              Winding rule WIND_NON_ZERO used, after construction, this is irrelevant.
     
    Constructor Summary
    Area()
              Constructs an empty Area
    Area(java.awt.Shape s)
              Constructs an Area from any given Shape.
     
    Method Summary
     void add(Area area)
              Performs an add (union) operation on this area with another Area.
     java.lang.Object clone()
              Create a new area of the same run-time type with the same contents as this one.
     boolean contains(double x, double y)
              Determines if the point (x,y) is contained within this Area.
     boolean contains(double x, double y, double w, double h)
              Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h is completely contained within this Area, returns false otherwise.
     boolean contains(Point2D p)
              Determines if the Point2D p is contained within this Area.
     boolean contains(Rectangle2D r)
              Determines if the Rectangle2D specified by r is completely contained within this Area, returns false otherwise.
    private  int createNodes(Area.Segment A, Area.Segment B)
              Find the intersections of two separate closed paths, A and B, split the segments at the intersection points, and create nodes pointing from one to the other
    private  int createNodesSelf(Area.Segment A)
              Find the intersections of a path with itself.
     Area createTransformedArea(AffineTransform at)
              Returns a new Area equal to this one, transformed by the AffineTransform at.
    (package private)  Area.Intersection[] cubicCubicIntersect(Area.CubicSegment curve1, Area.CubicSegment curve2)
              Returns a set of interesections between two Cubic segments Or null if no intersections were found.
    private  void deleteRedundantPaths(java.util.Vector paths)
              Deletes paths which are redundant from a list, (i.e.
     boolean equals(Area area)
              Compares two Areas.
     void exclusiveOr(Area area)
              Performs an exclusive-or operation on this Area.
     java.awt.Rectangle getBounds()
              Returns the bounds of this object in Rectangle format.
     Rectangle2D getBounds2D()
              Returns the bounding box of the Area.
     PathIterator getPathIterator(AffineTransform at)
              Returns a PathIterator object defining the contour of this Area, transformed by at.
     PathIterator getPathIterator(AffineTransform at, double flatness)
              Returns a flattened PathIterator object defining the contour of this Area, transformed by at and with a defined flatness.
    private  int getRecursionDepth(Area.CubicSegment curve)
              Returns the recursion depth necessary to approximate the curve by line segments within the error RS_EPSILON.
     void intersect(Area area)
              Performs an intersection operation on this Area.
     boolean intersects(double x, double y, double w, double h)
              Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h intersects any part of this Area.
     boolean intersects(Rectangle2D r)
              Determines if the Rectangle2D specified by r intersects any part of this Area.
     boolean isEmpty()
              Returns whether this area encloses any area.
     boolean isPolygonal()
              Determines whether the Area consists entirely of line segments
     boolean isRectangular()
              Determines if the Area is rectangular.
     boolean isSingular()
              Returns whether the Area consists of more than one simple (non self-intersecting) subpath.
    (package private)  Area.Intersection[] lineCubicIntersect(Area.LineSegment l, Area.CubicSegment c)
              Returns the intersections between a line and a cubic segment This is done through combining the line's equation with the parametric form of the Bezier and solving the resulting quadratic.
    (package private)  Area.Intersection[] lineQuadIntersect(Area.LineSegment l, Area.QuadSegment c)
              Returns the intersections between a line and a quadratic bezier Or null if no intersections are found1 This is done through combining the line's equation with the parametric form of the Bezier and solving the resulting quadratic.
    (package private)  Area.Intersection linesIntersect(Area.LineSegment a, Area.LineSegment b)
              Returns the intersection between two lines, or null if there is no intersection.
    private  java.util.Vector makeSegment(java.awt.Shape s)
              Helper method Turns a shape into a Vector of Segments
    (package private)  boolean pointEquals(Point2D a, Point2D b)
              Determines if two points are equal, within an error margin 'snap distance' This is package-private to avoid an accessor method.
    private  void recursiveSubdivide(CubicCurve2D c1, CubicCurve2D c2, int depth1, int depth2, double t1, double t2, double w1, double w2)
              Performs recursive subdivision:
     void reset()
              Clears the Area object, creating an empty area.
    private  void setDirection(java.util.Vector paths, boolean clockwise)
              Sets the winding direction of a Vector of paths
     void subtract(Area area)
              Performs a subtraction operation on this Area.
     void transform(AffineTransform at)
              Transforms this area by the AffineTransform at.
    private  java.util.Vector weilerAtherton(java.util.Vector segments)
              Performs the fundamental task of the Weiler-Atherton algorithm, traverse a list of segments, for each segment: Follow it, removing segments from the list and switching paths at each node.
     
    Methods inherited from class java.lang.Object
    equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait
     

    Field Detail

    EPSILON

    private static final double EPSILON
    General numerical precision

    See Also:
    Constant Field Values

    RS_EPSILON

    private static final double RS_EPSILON
    recursive subdivision epsilon - (see getRecursionDepth)

    See Also:
    Constant Field Values

    PE_EPSILON

    private static final double PE_EPSILON
    Snap distance - points within this distance are considered equal

    See Also:
    Constant Field Values

    solids

    java.util.Vector solids
    Segment vectors containing solid areas and holes This is package-private to avoid an accessor method.


    holes

    java.util.Vector holes
    Segment vectors containing solid areas and holes This is package-private to avoid an accessor method.


    cc_intersections

    private java.util.Vector cc_intersections
    Vector (temporary) storing curve-curve intersections


    windingRule

    private int windingRule
    Winding rule WIND_NON_ZERO used, after construction, this is irrelevant.

    Constructor Detail

    Area

    public Area()
    Constructs an empty Area


    Area

    public Area(java.awt.Shape s)
    Constructs an Area from any given Shape.

    If the Shape is self-intersecting, the created Area will consist of non-self-intersecting subpaths, and any inner paths which are found redundant in accordance with the Shape's winding rule will not be included.

    Method Detail

    add

    public void add(Area area)
    Performs an add (union) operation on this area with another Area.


    subtract

    public void subtract(Area area)
    Performs a subtraction operation on this Area.


    intersect

    public void intersect(Area area)
    Performs an intersection operation on this Area.


    exclusiveOr

    public void exclusiveOr(Area area)
    Performs an exclusive-or operation on this Area.


    reset

    public void reset()
    Clears the Area object, creating an empty area.


    isEmpty

    public boolean isEmpty()
    Returns whether this area encloses any area.


    isPolygonal

    public boolean isPolygonal()
    Determines whether the Area consists entirely of line segments


    isRectangular

    public boolean isRectangular()
    Determines if the Area is rectangular.

    This is strictly qualified. An area is considered rectangular if:

  • It consists of a single polygonal path.
  • It is oriented parallel/perpendicular to the xy axis
  • It must be exactly rectangular, i.e. small errors induced by transformations may cause a false result, although the area is visibly rectangular.


  • isSingular

    public boolean isSingular()
    Returns whether the Area consists of more than one simple (non self-intersecting) subpath.


    getBounds2D

    public Rectangle2D getBounds2D()
    Returns the bounding box of the Area.

    Unlike the CubicCurve2D and QuadraticCurve2D classes, this method will return the tightest possible bounding box, evaluating the extreme points of each curved segment.

    Specified by:
    getBounds2D in interface java.awt.Shape

    getBounds

    public java.awt.Rectangle getBounds()
    Returns the bounds of this object in Rectangle format. Please note that this may lead to loss of precision.

    Specified by:
    getBounds in interface java.awt.Shape

    clone

    public java.lang.Object clone()
    Create a new area of the same run-time type with the same contents as this one.


    equals

    public boolean equals(Area area)
    Compares two Areas.


    transform

    public void transform(AffineTransform at)
    Transforms this area by the AffineTransform at.


    createTransformedArea

    public Area createTransformedArea(AffineTransform at)
    Returns a new Area equal to this one, transformed by the AffineTransform at.


    contains

    public boolean contains(double x,
                            double y)
    Determines if the point (x,y) is contained within this Area.

    Specified by:
    contains in interface java.awt.Shape

    contains

    public boolean contains(Point2D p)
    Determines if the Point2D p is contained within this Area.

    Specified by:
    contains in interface java.awt.Shape

    contains

    public boolean contains(double x,
                            double y,
                            double w,
                            double h)
    Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h is completely contained within this Area, returns false otherwise.

    This method should always produce the correct results, unlike for other classes in geom.

    Specified by:
    contains in interface java.awt.Shape

    contains

    public boolean contains(Rectangle2D r)
    Determines if the Rectangle2D specified by r is completely contained within this Area, returns false otherwise.

    This method should always produce the correct results, unlike for other classes in geom.

    Specified by:
    contains in interface java.awt.Shape

    intersects

    public boolean intersects(double x,
                              double y,
                              double w,
                              double h)
    Determines if the rectangle specified by (x,y) as the upper-left and with width w and height h intersects any part of this Area.

    Specified by:
    intersects in interface java.awt.Shape

    intersects

    public boolean intersects(Rectangle2D r)
    Determines if the Rectangle2D specified by r intersects any part of this Area.

    Specified by:
    intersects in interface java.awt.Shape

    getPathIterator

    public PathIterator getPathIterator(AffineTransform at)
    Returns a PathIterator object defining the contour of this Area, transformed by at.

    Specified by:
    getPathIterator in interface java.awt.Shape

    getPathIterator

    public PathIterator getPathIterator(AffineTransform at,
                                        double flatness)
    Returns a flattened PathIterator object defining the contour of this Area, transformed by at and with a defined flatness.

    Specified by:
    getPathIterator in interface java.awt.Shape

    weilerAtherton

    private java.util.Vector weilerAtherton(java.util.Vector segments)
    Performs the fundamental task of the Weiler-Atherton algorithm, traverse a list of segments, for each segment: Follow it, removing segments from the list and switching paths at each node. Do so until the starting segment is reached. Returns a Vector of the resulting paths.


    getRecursionDepth

    private int getRecursionDepth(Area.CubicSegment curve)
    Returns the recursion depth necessary to approximate the curve by line segments within the error RS_EPSILON. This is done with Wang's formula: L0 = max{0<=i<=N-2}(|xi - 2xi+1 + xi+2|,|yi - 2yi+1 + yi+2|) r0 = log4(sqrt(2)*N*(N-1)*L0/8e) Where e is the maximum distance error (RS_EPSILON)


    recursiveSubdivide

    private void recursiveSubdivide(CubicCurve2D c1,
                                    CubicCurve2D c2,
                                    int depth1,
                                    int depth2,
                                    double t1,
                                    double t2,
                                    double w1,
                                    double w2)
    Performs recursive subdivision:


    cubicCubicIntersect

    Area.Intersection[] cubicCubicIntersect(Area.CubicSegment curve1,
                                            Area.CubicSegment curve2)
    Returns a set of interesections between two Cubic segments Or null if no intersections were found. The method used to find the intersection is recursive midpoint subdivision. Outline description: 1) Check if the bounding boxes of the curves intersect, 2) If so, divide the curves in the middle and test the bounding boxes again, 3) Repeat until a maximum recursion depth has been reached, where the intersecting curves can be approximated by line segments. This is a reasonably accurate method, although the recursion depth is typically around 20, the bounding-box tests allow for significant pruning of the subdivision tree. This is package-private to avoid an accessor method.


    lineQuadIntersect

    Area.Intersection[] lineQuadIntersect(Area.LineSegment l,
                                          Area.QuadSegment c)
    Returns the intersections between a line and a quadratic bezier Or null if no intersections are found1 This is done through combining the line's equation with the parametric form of the Bezier and solving the resulting quadratic. This is package-private to avoid an accessor method.


    lineCubicIntersect

    Area.Intersection[] lineCubicIntersect(Area.LineSegment l,
                                           Area.CubicSegment c)
    Returns the intersections between a line and a cubic segment This is done through combining the line's equation with the parametric form of the Bezier and solving the resulting quadratic. This is package-private to avoid an accessor method.


    linesIntersect

    Area.Intersection linesIntersect(Area.LineSegment a,
                                     Area.LineSegment b)
    Returns the intersection between two lines, or null if there is no intersection. This is package-private to avoid an accessor method.


    pointEquals

    boolean pointEquals(Point2D a,
                        Point2D b)
    Determines if two points are equal, within an error margin 'snap distance' This is package-private to avoid an accessor method.


    makeSegment

    private java.util.Vector makeSegment(java.awt.Shape s)
    Helper method Turns a shape into a Vector of Segments


    createNodes

    private int createNodes(Area.Segment A,
                            Area.Segment B)
    Find the intersections of two separate closed paths, A and B, split the segments at the intersection points, and create nodes pointing from one to the other


    createNodesSelf

    private int createNodesSelf(Area.Segment A)
    Find the intersections of a path with itself. Splits the segments at the intersection points, and create nodes pointing from one to the other.


    deleteRedundantPaths

    private void deleteRedundantPaths(java.util.Vector paths)
    Deletes paths which are redundant from a list, (i.e. solid areas within solid areas) Clears any nodes. Sorts the remaining paths into solids and holes, sets their orientation and sets the solids and holes lists.


    setDirection

    private void setDirection(java.util.Vector paths,
                              boolean clockwise)
    Sets the winding direction of a Vector of paths