no.geosoft.cc.geometry
Class Region

Object
  Region

All Implemented Interfaces:

Cloneable

public class Region

extends Object

implements Cloneable

A Region is simply an area, as the name implies, and is implemented as a so called "y-x-banded" array of rectangles; Each Region is made up of a certain number of rectangles sorted by y coordinate first, and then by x coordinate.

Furthermore, the rectangles are banded such that every rectangle with a given upper-left y coordinate (y1) will have the same lower-right y coordinate (y2) and vice versa. If a rectangle has scanlines in a band, it will span the entire vertical distance of the band. This means that some areas that could be merged into a taller rectangle will be represented as several shorter rectangles to account for shorter rectangles to its left or right but within its "vertical scope".

An added constraint on the rectangles is that they must cover as much horizontal area as possible. E.g. no two rectangles in a band are allowed to touch. Whenever possible, bands will be merged together to cover a greater vertical distance (and thus reduce the number of rectangles). Two bands can be merged only if the bottom of one touches the top of the other and they have rectangles in the same places (of the same width, of course). This maintains the y-x-banding.

Region operations includes add (union), subtract, intersect, and exclusive-or.

This class corresponds to Region.c of the X11 distribution and the implemntation is based on it.

The Region is essentially equivalent to an AWT Area but with different back-end implementation. Becnhmarking proves it more than 100 times faster than AWT Area for binary CAG operations,

Thanks to:

• Bryan Lin @ China Minmetals Corporation - for identifying synchronization errors when run on the MS WindowsXP platform.
• Maxim Butov @ Belhard - for identifying error in the isInside(Rect) method.

Author:

GeoSoft

Constructor Summary

Region()
Create an empty region.

Region(Box box)
Create a region consisting of one rectangle as specified.

Region(int[] x, int[] y)
Create the region covering the (possibly complex) polygon specified by the x and y parameters.

Region(int x, int y, int width, int height)
Create a region consisting of one rectangle as specified.

Region(Rect rectangle)
Create a region constituting of a single rectangle as specified.

Region(Region region)
Create a region as a copy of the specified region.

Method Summary

void	clear() Clear the region.
Object	clone() Clone this region.
void	collapse() Collapse the region into its extent box.
Area	createArea() Convert this region to an AWT Area.
boolean	equals(Object object) Return true if this region equals the specified object.
Rect	getExtent() Return the extent of the region.
int	getNRectangles() Return the number of rectangles in the region.
void	intersect(Rect rectangle) Leave this region as the intersection between this region and the specified rectangle.
void	intersect(Region region) Leave this region as the intersection between this region and the specified region.
static Region	intersect(Region region, Rect rectangle) Create a new region as the intersection between a region and a rectangle.
static Region	intersect(Region r1, Region r2) Create a new region as the intersection between two specified regions.
boolean	isEmpty() Return true if the region is empty.
boolean	isInside(int x, int y) Return true if the specified point is inside this region.
boolean	isInside(Rect rectangle) Return true if the specified rectangle is inside this region.
boolean	isInsideOf(Rect rectangle) Return true if this region is inside of the specified rectangle.
boolean	isIntersecting(Rect rectangle) Return true if the specified rectangle intersect this region.
boolean	isIntersecting(Region region) Return true if the specified region intersect this region.
void	offset(int dx, int dy) Offset the entire region a specified distance.
void	set(Rect rectangle) Set the content of this region according to the specified rectangle.
void	set(Region region) Set the content of this region according to the specified region.
void	subtract(Rect rectangle) Subtract the specified rectangle from this region.
void	subtract(Region region) Subtract the specified region from this region.
static Region	subtract(Region region, Rect rectangle) Create a new region as the subtraction of a rectangle from a region.
static Region	subtract(Region r1, Region r2) Create a new region as the subtraction of one region from another.
void	union(Rect rectangle) Union this region with the specified rectangle.
void	union(Region region) Union this region with the specified region.
static Region	union(Region region, Rect rectangle) Create a new region as the union between a region and a rectangle.
static Region	union(Region r1, Region r2) Create a new region as the union between two specified regions.
void	xor(Rect rectangle) Leave the exclusive-or between this and the specified rectangle in this region.
void	xor(Region region) Leave the exclusive-or between this and the specified region in this region.
static Region	xor(Region region, Rect rectangle) Do an exlusive-or operation between a regions and a rectangle and return the result.
static Region	xor(Region r1, Region r2) Do an exlusive-or operation between two regions and return the result.

Methods inherited from class Object

getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Constructor Detail

Region

public Region()

Create an empty region. Corresponds to XCreateRegion of X11.

Region

public Region(int[] x,
              int[] y)

Create the region covering the (possibly complex) polygon specified by the x and y parameters. Corresponds to XPolygonRegion of X11.

Parameters:

x - X values of polygon vertices.

y - Y values of polygon vertices.

Region

public Region(Rect rectangle)

Create a region constituting of a single rectangle as specified.

Parameters:

rectangle - Rectangle to create region from.

Region

public Region(int x,
              int y,
              int width,
              int height)

Create a region consisting of one rectangle as specified.

Parameters:

x - X position of upper left corner of rectangle.

y - Y position of upper left corner of rectangle.

width - Width of rectangle.

height - Height of rectangle.

Region

public Region(Box box)

Create a region consisting of one rectangle as specified.

Parameters:

box - Box specification of rectangle to create region from.

Region

public Region(Region region)

Create a region as a copy of the specified region.

Parameters:

region - Region to copy.

Method Detail

clone

public Object clone()

Clone this region.

Returns:

Clone of this region.

createArea

public Area createArea()

Convert this region to an AWT Area.

Note: The AWT classes are referenced explicitly here rather tham importing them to indicate that the Region implementation does not dependent on the AWT.

Returns:

Area equivalent of this rectangle.

set

public void set(Region region)

Set the content of this region according to the specified region.

Parameters:

region - Region to copy.

set

public void set(Rect rectangle)

Set the content of this region according to the specified rectangle.

Parameters:

rectangle - Rectangle to set region according to.

clear

public void clear()

Clear the region.

equals

public boolean equals(Object object)

Return true if this region equals the specified object. Corrensponds to XEqualRegion of X11.

Parameters:

object - Object to check against.

Returns:

True if the two regions equals, false otherwise.

Throws:

ClassCastException - if object is not of type Region.

isEmpty

public boolean isEmpty()

Return true if the region is empty. Corresponds to XEmptyRegion in X11.

Returns:

True if the region is empty, false otherwise.

offset

public void offset(int dx,
                   int dy)

Offset the entire region a specified distance. Corresponds to XOffsetRegion in X11.

Parameters:

dx - Offset in x direction.

dy - Offset in y direction.

isIntersecting

public boolean isIntersecting(Region region)

Return true if the specified region intersect this region.

Parameters:

region - Region to check against.

Returns:

True if the region intersects this one, false otherwise.

isIntersecting

public boolean isIntersecting(Rect rectangle)

Return true if the specified rectangle intersect this region.

Parameters:

rectangle - Rectangle to check against.

Returns:

True if the rectangle intersects this, false otherwise.

isInside

public boolean isInside(int x,
                        int y)

Return true if the specified point is inside this region. This method corresponds to XPointInRegion in X11.

Parameters:

x - X part of point to check.

y - Y part of point to check.

Returns:

True if the point is inside the region, false otherwise.

isInside

public boolean isInside(Rect rectangle)

Return true if the specified rectangle is inside this region. This method corresponds to XRectInRegion in X11.

Parameters:

rectangle - Rectangle to check.

Returns:

True if the rectangle is inside this region, false otherwise.

isInsideOf

public boolean isInsideOf(Rect rectangle)

Return true if this region is inside of the specified rectangle.

Parameters:

rectangle - Rectangle to check if this is inside of.

Returns:

True if this region is inside the specified rectangle, false otherwise.

getExtent

public Rect getExtent()

Return the extent of the region. Correspond to XClipBox in X11.

Returns:

The extent of this region.

getNRectangles

public int getNRectangles()

Return the number of rectangles in the region. In case the number is getting very high, the application might choose to call collapse().

Returns:

Number of rectangles this region consists of.

collapse

public void collapse()

Collapse the region into its extent box. Useful if the region becomes very complex (number of rectangles is getting high) and the client accepts the (in general) coarser result region.

union

public void union(Region region)

Union this region with the specified region. Corresponds to XUnionRegion in X11.

Parameters:

region - Region to union this with.

union

public void union(Rect rectangle)

Union this region with the specified rectangle. Corresponds to XUnionRectWithRegion in X11.

Parameters:

rectangle - Rectangle to union this with.

union

public static Region union(Region r1,
                           Region r2)

Create a new region as the union between two specified regions.

Parameters:

r1 - First region to union.

r2 - Second region to union.

Returns:

Union of the two specified regions.

union

public static Region union(Region region,
                           Rect rectangle)

Create a new region as the union between a region and a rectangle.

Parameters:

region - Region to union.

rectangle - Rectangle to intersect with.

Returns:

Union of the region and the rectangle.

intersect

public void intersect(Region region)

Leave this region as the intersection between this region and the specified region. Corresponds to XIntersectRegion in X11.

Parameters:

region - Region to intersect this with.

intersect

public void intersect(Rect rectangle)

Leave this region as the intersection between this region and the specified rectangle.

Parameters:

rectangle - Rectangle to intersect this with.

intersect

public static Region intersect(Region r1,
                               Region r2)

Create a new region as the intersection between two specified regions.

Parameters:

r1 - First region to intersect.

r2 - Second region to intersect.

Returns:

Intersection between the two specified regions.

intersect

public static Region intersect(Region region,
                               Rect rectangle)

Create a new region as the intersection between a region and a rectangle.

Parameters:

region - Region to intersect.

rectangle - Rectangle to intersect with.

Returns:

Intersection between the region and the rectangle.

subtract

public void subtract(Region region)

Subtract the specified region from this region. Corresponds to XSubtractRegion in X11.

Parameters:

region - Region to subtract from this region.

subtract

public void subtract(Rect rectangle)

Subtract the specified rectangle from this region.

Parameters:

rectangle - Rectangle to subtract from this region.

subtract

public static Region subtract(Region r1,
                              Region r2)

Create a new region as the subtraction of one region from another.

Parameters:

r1 - Region to subtract from.

r2 - Region to subtract.

Returns:

Subtraction of the two specified regions.

subtract

public static Region subtract(Region region,
                              Rect rectangle)

Create a new region as the subtraction of a rectangle from a region.

Parameters:

region - Region to subtract from.

rectangle - Ractangle to subtract.

Returns:

Subtraction of the two specified regions.

xor

public void xor(Region region)

Leave the exclusive-or between this and the specified region in this region. Corresponds to the XXorRegion in X11.

Parameters:

region - Region to xor this region with.

xor

public void xor(Rect rectangle)

Leave the exclusive-or between this and the specified rectangle in this region.

Parameters:

rectangle - Rectangle to xor this region with.

xor

public static Region xor(Region r1,
                         Region r2)

Do an exlusive-or operation between two regions and return the result.

Parameters:

r1 - First region to xor.

r2 - Second region to xor.

Returns:

Result of operation.

xor

public static Region xor(Region region,
                         Rect rectangle)

Do an exlusive-or operation between a regions and a rectangle and return the result.

Parameters:

region - Region to xor.

rectangle - Rectangle to xor with.

Returns:

Result of operation.