org.kynosarges.tektosyne.geometry

Class RectD

java.lang.Object

org.kynosarges.tektosyne.geometry.RectD

public final class RectD
extends java.lang.Object

Represents a rectangular region in two-dimensional space, using Double coordinates. RectI contains two immutable PointD locations, defining the opposite corners of a rectangle. Use RectI to represent rectangles with Integer coordinates.

Field Summary

Fields

Modifier and Type	Field and Description
static RectD	EMPTY An empty read-only RectD.
PointD	max The greatest coordinates within the RectD.
PointD	min The smallest coordinates within the RectD.

Constructor Summary

Constructors

Constructor and Description
RectD() Creates a RectD with all coordinates set to zero.
RectD(double minX, double minY, double maxX, double maxY) Creates a RectD with the specified Double coordinates.
RectD(PointD min, PointD max) Creates a RectD with the specified PointD coordinates.

Method Summary

Modifier and Type	Method and Description
PointD	center() Gets the PointD at the center of the RectD.
RectI	circumscribe() Circumscribes a RectI around the RectD.
static RectD	circumscribe(PointD... points) Circumscribes a RectD around the specified PointD coordinates.
boolean	contains(double x, double y) Determines whether the RectD contains the specified Double coordinates.
boolean	contains(PointD point) Determines whether the RectD contains the specified PointD coordinates.
boolean	contains(RectD rect) Determines whether the RectD entirely contains the specified instance.
boolean	containsOpen(double x, double y) Determines whether the RectD contains the specified Double coordinates, excluding the x- and y-coordinates of max.
boolean	containsOpen(PointD point) Determines whether the RectD contains the specified PointD coordinates, excluding the x- and y-coordinates of max.
PointD	distanceVector(PointD q) Finds the distance vector from the specified PointD coordinates to the nearest edges of the RectD.
boolean	equals(java.lang.Object obj) Compares the specified Object to this RectD instance.
static boolean	equals(RectD a, RectD b, double epsilon) Compares two RectD instances for equality, given the specified epsilon.
static RectD[]	fromDoubles(double... rects) Converts the specified Double array to a RectD array.
int	hashCode() Returns a hash code for the RectD.
double	height() Gets the height the RectD.
LineD	intersect(LineD line) Finds the intersection of the RectD with the specified LineD.
PointD[]	intersect(PointD[] polygon) Intersects the RectD with the specified arbitrary PointD polygon.
RectD	intersect(RectD rect) Finds the intersection of the RectD with the specified instance.
boolean	intersectsWith(LineD line) Determines whether the RectD intersects with the specified LineD.
boolean	intersectsWith(RectD rect) Determines whether the RectD intersects with the specified instance.
RectLocation	locate(PointD q) Determines the location of the specified PointD relative to the RectD, using exact coordinate comparisons.
RectLocation	locate(PointD q, double epsilon) Determines the location of the specified PointD relative to the RectD, given the specified epsilon for coordinate comparisons.
RectD	offset(double x, double y) Offsets the RectD by the specified Double distances.
RectD	offset(PointD vector) Offsets the RectD by the specified PointD vector.
RectI	round() Converts the RectD to a RectI by rounding coordinates to the nearest Integer values.
static double[]	toDoubles(RectD... rects) Converts the specified RectD array to a Double array.
RectI	toRectI() Converts the RectD to a RectI by truncating coordinates to the nearest Integer values.
java.lang.String	toString() Returns a String representation of the RectD.
RectD	union(RectD rect) Finds the union of the RectD with the specified instance.
double	width() Gets the width the RectD.

Methods inherited from class java.lang.Object

clone, finalize, getClass, notify, notifyAll, wait, wait, wait

Field Detail

min

public final PointD min

The smallest coordinates within the RectD. Both dimensions are equal to or less than the corresponding max dimensions.

max

public final PointD max

The greatest coordinates within the RectD. Both dimensions are equal to or greater than the corresponding min dimensions.

EMPTY

public static final RectD EMPTY

An empty read-only RectD. min and max are both set to PointD.EMPTY.

Constructor Detail

RectD

public RectD()

Creates a RectD with all coordinates set to zero. min and max are both set to PointD.EMPTY.

RectD

public RectD(double minX,
             double minY,
             double maxX,
             double maxY)

Creates a RectD with the specified Double coordinates.

Parameters:

minX - the smallest x-coordinate within the RectD

minY - the smallest y-coordinate within the RectD

maxX - the greatest x-coordinate within the RectD

maxY - the greatest y-coordinate within the RectD

Throws:

java.lang.IllegalArgumentException - if maxX is less than minX, or maxY is less than minY

RectD

public RectD(PointD min,
             PointD max)

Creates a RectD with the specified PointD coordinates.

Parameters:

min - the smallest coordinates within the RectD

max - the greatest coordinates within the RectD

Throws:

java.lang.IllegalArgumentException - if any dimension of max is less than the corresponding dimension of min

java.lang.NullPointerException - if min or max is null

Method Detail

center

public PointD center()

Gets the PointD at the center of the RectD. Returns a PointD that is offset from min by half the distance from min to max.

Returns:

the PointD at the center of the RectD

circumscribe

public RectI circumscribe()

Circumscribes a RectI around the RectD. The RectI extends from the Fortran.floor(double) of min to the Fortran.ceiling(double) of max.

Returns:

a RectI that entirely covers the RectD

Throws:

java.lang.ArithmeticException - if any coordinate overflows Integer

circumscribe

public static RectD circumscribe(PointD... points)

Circumscribes a RectD around the specified PointD coordinates. Sets both dimensions of min to the smallest coordinates, and both dimensions of max to the greatest coordinates, found among any points.

Parameters:

points - an array of PointD coordinates whose bounds to determine

Returns:

the smallest RectD that contains all specified points

Throws:

java.lang.NullPointerException - if points is null or empty, or contains any null elements

contains

public boolean contains(double x,
                        double y)

Determines whether the RectD contains the specified Double coordinates.

Parameters:

x - the x-coordinate to examine

y - the y-coordinate to examine

Returns:

true if both x and y fall within the range of coordinates defined by min and max, else false

contains

public boolean contains(PointD point)

Determines whether the RectD contains the specified PointD coordinates.

Parameters:

point - the PointD to examine

Returns:

true if both dimensions of point fall within the range of coordinates defined by min and max, else false

Throws:

java.lang.NullPointerException - if point is null

containsOpen

public boolean containsOpen(double x,
                            double y)

Determines whether the RectD contains the specified Double coordinates, excluding the x- and y-coordinates of max.

Parameters:

x - the x-coordinate to examine

y - the y-coordinate to examine

Returns:

true if both x and y fall within the range of coordinates defined by min (inclusive) and max (exclusive), else false

containsOpen

public boolean containsOpen(PointD point)

Determines whether the RectD contains the specified PointD coordinates, excluding the x- and y-coordinates of max.

Parameters:

point - the PointD to examine

Returns:

true if both dimensions of point fall within the range of coordinates defined by min (inclusive) and max (exclusive), else false

Throws:

java.lang.NullPointerException - if point is null

contains

public boolean contains(RectD rect)

Determines whether the RectD entirely contains the specified instance.

Parameters:

rect - the RectD to examine

Returns:

true if both min and max of the specified rect fall within the range coordinates defined by this instance, else false

Throws:

java.lang.NullPointerException - if rect is null

distanceVector

public PointD distanceVector(PointD q)

Finds the distance vector from the specified PointD coordinates to the nearest edges of the RectD. The returned coordinates are negative if the corresponding dimension of q if less than that of min, and positive if it is greater than max.

Parameters:

q - the PointD to examine

Returns:

a PointD whose dimensions equal zero if they fall within the corresponding dimensions of min and max, else the signed difference to the nearest edge coordinate

Throws:

java.lang.NullPointerException - if q is null

equals

public static boolean equals(RectD a,
                             RectD b,
                             double epsilon)

Compares two RectD instances for equality, given the specified epsilon.

Parameters:

a - the first RectD to compare

b - the second RectD to compare

epsilon - the maximum absolute difference where the corresponding coordinates of a and b are considered equal

Returns:

true if the absolute difference between all corresponding coordinates of a and b is no greater than epsilon, else false

Throws:

java.lang.IllegalArgumentException - if epsilon is less than zero

java.lang.NullPointerException - if a or b is null

fromDoubles

public static RectD[] fromDoubles(double... rects)

Converts the specified Double array to a RectD array. The returned array has a quarter as many elements as the specified rects and retains the same coordinate sequence.

Parameters:

rects - an array containing the coordinates min.x, min.y, max.x, max.y of RectD instances, stored in successive index positions per RectD

Returns:

the RectD array created from rects

Throws:

java.lang.IllegalArgumentException - if the length of rects is not divisible by four, or if any max coordinate is less than the corresponding min coordinate

java.lang.NullPointerException - if rects is null

height

public double height()

Gets the height the RectD. Never negative but may be zero.

Returns:

the difference between the x-coordinates of max and min

intersect

public LineD intersect(LineD line)

Finds the intersection of the RectD with the specified LineD. Performs the Liang-Barsky line clipping algorithm. This Java implementation was adapted from the C implementation by Daniel White, published at Skytopia.

Parameters:

line - the LineD to intersect with the RectD

Returns:

a LineD that contains the intersection of line with the RectD, if any intersection was found, else null

Throws:

java.lang.NullPointerException - if line is null

intersect

public PointD[] intersect(PointD[] polygon)

Intersects the RectD with the specified arbitrary PointD polygon. Performs the Sutherland–Hodgman polygon clipping algorithm, optimized for an axis-aligned RectD as the clipping polygon. At intersection points, the border coordinates of the RectD are copied rather than computed, allowing exact floating-point comparisons.

The specified polygon and the returned intersection are implicitly assumed to be closed, with an edge connecting first and last vertex. Therefore, all vertices should be different.

Unless the specified polygon is convex, the returned intersection may represent multiple polygons, connected across the borders of RectD.

Parameters:

polygon - an array of PointD coordinates describing the vertices of the polygon to intersect with the RectD

Returns:

the intersection of polygon with the RectD, if an intersection was found, else null

Throws:

java.lang.NullPointerException - if polygon is null or empty, or contains any null elements

intersect

public RectD intersect(RectD rect)

Finds the intersection of the RectD with the specified instance.

Parameters:

rect - the RectD to intersect with this instance

Returns:

a RectD that contains the intersection of rect with this instance, if any intersection was found, else null

Throws:

java.lang.NullPointerException - if rect is null

intersectsWith

public boolean intersectsWith(LineD line)

Determines whether the RectD intersects with the specified LineD. Performs the same Liang-Barsky line clipping algorithm as intersect(LineD) but without computing the intersecting line segment.

Parameters:

line - the LineD to examine

Returns:

true if line intersects the RectD, else false

Throws:

java.lang.NullPointerException - if line is null

intersectsWith

public boolean intersectsWith(RectD rect)

Determines whether the RectD intersects with the specified instance.

Parameters:

rect - the RectD to examine

Returns:

true if rect shares any coordinates with this instance, else false

Throws:

java.lang.NullPointerException - if rect is null

locate

public RectLocation locate(PointD q)

Determines the location of the specified PointD relative to the RectD, using exact coordinate comparisons.

Parameters:

q - the PointD coordinates to examine

Returns:

a RectLocation indicating the location of q relative to the RectD in each dimension

Throws:

java.lang.NullPointerException - if q is null

locate

public RectLocation locate(PointD q,
                           double epsilon)

Determines the location of the specified PointD relative to the RectD, given the specified epsilon for coordinate comparisons.

Parameters:

q - the PointD coordinates to examine

epsilon - the maximum absolute difference at which coordinates should be considered equal

Returns:

a RectLocation indicating the location of q relative to the RectD in each dimension

Throws:

java.lang.IllegalArgumentException - if epsilon is less than zero

java.lang.NullPointerException - if q is null

offset

public RectD offset(double x,
                    double y)

Offsets the RectD by the specified Double distances.

Parameters:

x - the horizontal offset applied to the RectD

y - the vertical offset applied to the RectD

Returns:

a RectD whose min and max equal those of the current instance, with x and y added to all corresponding dimensions

offset

public RectD offset(PointD vector)

Offsets the RectD by the specified PointD vector.

Parameters:

vector - the PointD offset applied to the RectD

Returns:

a RectD whose min and max equal those of the current instance, with vector added to both points

Throws:

java.lang.NullPointerException - if vector is null

round

public RectI round()

Converts the RectD to a RectI by rounding coordinates to the nearest Integer values. Uses PointD.round() for rounding.

Returns:

a RectI whose RectI.min and RectI.max points equal the corresponding points of the RectD, with each coordinate rounded to the nearest Integer value

Throws:

java.lang.ArithmeticException - if any coordinate overflows Integer

toDoubles

public static double[] toDoubles(RectD... rects)

Converts the specified RectD array to a Double array. The returned array has four times as many elements as the specified rects and retains the same coordinate sequence.

Parameters:

rects - the RectD array to convert

Returns:

an array containing the coordinates min.x, min.y, max.x, max.y for all rects, stored in successive index positions per RectD

Throws:

java.lang.NullPointerException - if rects or any of its elements is null

toRectI

public RectI toRectI()

Converts the RectD to a RectI by truncating coordinates to the nearest Integer values. Uses Integer casts for truncation.

Returns:

a RectI whose RectI.min and RectI.max points equal the corresponding points of the RectD, with each coordinate truncated to the nearest Integer value

Throws:

java.lang.ArithmeticException - if any coordinate overflows Integer

union

public RectD union(RectD rect)

Finds the union of the RectD with the specified instance.

Parameters:

rect - the RectD to combine with this instance

Returns:

a RectD that contains the union of rect with this instance

Throws:

java.lang.NullPointerException - if rect is null

width

public double width()

Gets the width the RectD. Never negative but may be zero.

Returns:

the difference between the y-coordinates of max and min

equals

public boolean equals(java.lang.Object obj)

Compares the specified Object to this RectD instance.

Overrides:

equals in class java.lang.Object

Parameters:

obj - the Object to compare to this instance

Returns:

true if obj is not null and a RectD instance whose min and max equal those of this instance, else false

hashCode

public int hashCode()

Returns a hash code for the RectD.

Overrides:

hashCode in class java.lang.Object

Returns:

an Integer hash code for the RectD

toString

public java.lang.String toString()

Returns a String representation of the RectD.

Overrides:

toString in class java.lang.Object

Returns:

a String containing the values of min and max