de.thaw.comb

Class AbstractSegment

java.lang.Object

de.thaw.comb.AbstractSegment

All Implemented Interfaces:

NodePair, Segment, Vector, Comparable<Segment>, Iterable<Segment>

Direct Known Subclasses:

AbstractSegment.Fragment, SourceSegment

abstract class AbstractSegment
extends Object
implements Segment, Vector, Iterable<Segment>

Implements the common structure and behaviour shared by all Segments in this project. Each AbstractSegment may be split into two other AbstractSegments, yielding a recursive composition, implemented as a Composite pattern, with this abstract class defining the "Component" participant. Concrete implementations of this class participate either as "Leaf" or as "Composite", depending on whether or not fragments (children) exist.

This class implements the Iterable interface such that iteration is performed on all Leafs in the composition. In other words, the iterator touches every fragment created by splitting. For example, if this segment has been split exactly once, the iterator touches 2 fragments; if this segment has been split twice, the iterator touches 3 fragments. If this segment has never been split, the iterator touches only 1 fragment, which is this segment itself. The iterator always touches at least 1 fragment. Note that fragments are Segments themselves.

Because of this it is easy to have loops touch every fragment of this segment, even if it was split many times:

     for (Segment fragment : segment) { ... }
 

See Also:

Segment, parent(), fragments

Nested Class Summary

Nested Classes

Modifier and Type	Class and Description
(package private) static class	AbstractSegment.Fragment A Segment implementation representing incomplete fragments of segments read from source data.
(package private) class	AbstractSegment.FragmentIterator An iterator to perform a depth-first traversal of the Composite tree below this segment, returning all Leafs.

Field Summary

Fields

Modifier and Type	Field and Description
protected Node	end
protected AbstractSegment[]	fragments The children of this Composite in the composition (if any).
(package private) static double	MIN_FRAGMENT_LENGTH
protected Node	start

Fields inherited from interface de.thaw.comb.util.Vector

FULL_CIRCLE, RIGHT_ANGLE, SEMI_CIRCLE

Constructor Summary

Constructors

Constructor and Description
AbstractSegment(Node start, Node end)

Method Summary

Modifier and Type	Method and Description
void	addBestLeftMatch(Segment bestMatch)
void	addBestRightMatch(Segment bestMatch)
Vector	aligned(Vector v) Compares this vector to the specified vector with regards to their convergence.
void	analyse(Analyser visitor)
double	bearing() The angle from grid north to the vector's direction, measured clockwise.
(package private) double	bearingDegrees()
int	compareTo(Segment other)
double	distance() The distance of the two nodes.
double	easting() The ordinate (horizontal / longitudinal) aspect of the vector's coordinate representation.
Node	end()
Node	findPerpendicularFoot(Node node)
boolean	isAligned(Vector v) Compares this vector's bearing to the specified vector's bearing.
Iterator<Segment>	iterator() An iterator over all segments, including any fragments this segment may have been split up into.
Node	midPoint() A node located exactly half-way between the two nodes.
double	northing() The abscissa (vertical / latitudinal) aspect of the vector's coordinate representation.
Node	other(Node node) The opposite node of the pair.
protected abstract AbstractSegment	parent() The parent of this object in the composition tree.
double	relativeBearing(Vector v) The angle from this vector's direction to the specified vector's direction, measured counterclockwise or clockwise, whichever is nearer.
(package private) void	reverse()
Vector	reversed() Returns a reversed representation of this vector.
SourceSegment	root()
boolean	shouldIgnore() Whether this Segment was split into two new Segments.
void	splitAt(Node node, SplitQueueListener listener) Split this Segment at the given node.
void	splitCloseParallels(SplitQueueListener listener)
Collection<Segment>	splitTargets()
Node	start()
String	toString()

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait

Methods inherited from interface java.lang.Iterable

forEach, spliterator

Field Detail

start

protected Node start

end

protected Node end

fragments

protected AbstractSegment[] fragments

The children of this Composite in the composition (if any). null iff this object does not represent a Composite, but a Leaf. A split converts this object from a Leaf into a Composite by assigning a non-null value to this field; in particular, a split creates exactly two fragments, thus an array of size 2 must be assigned.

MIN_FRAGMENT_LENGTH

static final double MIN_FRAGMENT_LENGTH

See Also:

Constant Field Values

Constructor Detail

AbstractSegment

AbstractSegment(Node start,
                Node end)

Method Detail

root

public SourceSegment root()

Specified by:

root in interface Segment

parent

protected abstract AbstractSegment parent()

The parent of this object in the composition tree. null if this object is the root of the tree.

Returns:

The parent or null

start

public Node start()

Specified by:

start in interface Segment

end

public Node end()

Specified by:

end in interface Segment

shouldIgnore

public boolean shouldIgnore()

Description copied from interface: Segment

Whether this Segment was split into two new Segments.

The SPLITTEN algorithm is defined to remove the original segment that was split into two parts from the collection of line parts to be split. Keeping the original would only duplicate work as the splitting is based on nodes, and both of the original's nodes are also present in its two parts after it was split. Rather than removing (which would likely be expensive), we introduce a simple flag to skip any line part that has already been split.

Specified by:

shouldIgnore in interface Segment

See Also:

Segment.splitAt(Node,SplitQueueListener)

midPoint

public Node midPoint()

Description copied from interface: NodePair

A node located exactly half-way between the two nodes.

Specified by:

midPoint in interface NodePair

Returns:

a (possibly new) Node object between the nodes

splitCloseParallels

public void splitCloseParallels(SplitQueueListener listener)

Specified by:

splitCloseParallels in interface Segment

splitTargets

public Collection<Segment> splitTargets()

Specified by:

splitTargets in interface Segment

findPerpendicularFoot

public Node findPerpendicularFoot(Node node)

Specified by:

findPerpendicularFoot in interface Segment

splitAt

public void splitAt(Node node,
                    SplitQueueListener listener)

Description copied from interface: Segment

Split this Segment at the given node. This Segment will be marked as having been split so that it will be ignored by future processing steps. The split will be reported to the split queue listener so that the two fragments created by the split can again be used for splitting.

Specified by:

splitAt in interface Segment

See Also:

Segment.shouldIgnore()

iterator

public Iterator<Segment> iterator()

An iterator over all segments, including any fragments this segment may have been split up into.

Specified by:

iterator in interface Iterable<Segment>

Returns:

an Iterator.

See Also:

AbstractSegment, AbstractSegment.FragmentIterator

analyse

public void analyse(Analyser visitor)

Specified by:

analyse in interface Segment

addBestLeftMatch

public void addBestLeftMatch(Segment bestMatch)

Specified by:

addBestLeftMatch in interface Segment

addBestRightMatch

public void addBestRightMatch(Segment bestMatch)

Specified by:

addBestRightMatch in interface Segment

compareTo

public int compareTo(Segment other)

Specified by:

compareTo in interface Comparable<Segment>

toString

public String toString()

Overrides:

toString in class Object

other

public Node other(Node node)

Description copied from interface: NodePair

The opposite node of the pair. If one of the two nodes in the pair is provided, the one not provided is returned. The behaviour when the given value is not a node in this pair is currently undefined; clients should expect an AssertionError in that case.

Specified by:

other in interface NodePair

Parameters:

node - the pair member that shouldn't be returned

Returns:

the pair member that isn't equal to node

easting

public double easting()

Description copied from interface: Vector

The ordinate (horizontal / longitudinal) aspect of the vector's coordinate representation.

Specified by:

easting in interface Vector

Returns:

the difference in easting (in internal units)

northing

public double northing()

Description copied from interface: Vector

The abscissa (vertical / latitudinal) aspect of the vector's coordinate representation.

Specified by:

northing in interface Vector

Returns:

the difference in northing (in internal units)

distance

public double distance()

Description copied from interface: NodePair

The distance of the two nodes.

Specified by:

distance in interface NodePair

Specified by:

distance in interface Vector

Returns:

the length between the nodes (in internal units)

bearing

public double bearing()

Description copied from interface: Vector

The angle from grid north to the vector's direction, measured clockwise. This value must always be returned in radians, facilitating easy use with Math.

For example, if a vector pointed to the west, this method would return 3/2 π (equal to 270°).

It is strongly recommended for implementations to return bearings normalised to the interval [0, 2 π), but clients should not depend upon this behaviour.

Specified by:

bearing in interface Vector

Returns:

the vector's bearing (direction)

See Also:

SimpleVector.normaliseAbsoluteBearing(double), Bearing (Wikipedia)

bearingDegrees

double bearingDegrees()

relativeBearing

public double relativeBearing(Vector v)

The angle from this vector's direction to the specified vector's direction, measured counterclockwise or clockwise, whichever is nearer.

Specified by:

relativeBearing in interface Vector

Parameters:

v - the vector to calculate the bearing of in relation to this vector

Returns:

relative bearing in interval [−π, π); 0.0 if v is zero-length

See Also:

SimpleVector.normaliseRelativeBearing(double), Relative bearing (Wikipedia)

reversed

public Vector reversed()

Description copied from interface: Vector

Returns a reversed representation of this vector.

Specified by:

reversed in interface Vector

Returns:

a view of this vector, reversed

reverse

void reverse()

aligned

public Vector aligned(Vector v)

Description copied from interface: Vector

Compares this vector to the specified vector with regards to their convergence. Implementations might use code that basically produces the same result as the following line does:

 return isAligned(v) ? clone() : reversed();
 

If the vectors already are aligned, implementations are free to return either this itself or another Vector object of equivalent value, at their option.

Specified by:

aligned in interface Vector

Parameters:

v - the vector to be compared with this one

Returns:

a view of this vector that is aligned with v

See Also:

Vector.isAligned(de.thaw.comb.util.Vector)

isAligned

public boolean isAligned(Vector v)

Description copied from interface: Vector

Compares this vector's bearing to the specified vector's bearing. For the purpose of this interface, two vectors are defined as being "aligned" if the absolute value of their relative bearing is less than a right angle. In other words, they are aligned if they form an acute angle and not aligned if they form an obtuse angle.

Implementations might use code that basically produces the same result as the following line does:

 return Math.abs( relativeBearing(v) ) < RIGHT_ANGLE;
 

The result of this method if the vectors are orthogonal is undefined.

Specified by:

isAligned in interface Vector

Parameters:

v - the vector to be compared with this one

Returns:

whether the two vectors differ by an acute angle

See Also:

Vector.relativeBearing(de.thaw.comb.util.Vector)