• Home
• org.kynosarges
• tektosyne
• 6.0.0
• source code
• SubdivisionSearch.java

×

Project download

Many resources are needed to download a project. Please understand that we have to compensate our server costs. Thank you in advance.
Project price only 1 $

You can buy this project and download/modify it how often you want.

org.kynosarges.tektosyne.subdivision.SubdivisionSearch Maven / Gradle / Ivy

package org.kynosarges.tektosyne.subdivision;

import java.util.*;
import org.kynosarges.tektosyne.geometry.*;

/**
 * Provides a fast search structure for a planar {@link Subdivision}.
 * Creates a search structure that achieves a query time of O(log n) for point location
 * in a planar {@link Subdivision} with n full edges. However, the search structure itself
 * occupies O(n) fairly big objects which require O(n log n) steps to construct, and must
 * be recreated whenever the underlying {@link Subdivision} changes.
 * 

 * Moreover, {@link SubdivisionSearch} requires a minimum epsilon of 1e-10 for coordinate
 * comparisons to reliably construct its search structure, and must use the construction
 * epsilon for all point location queries. Use the brute force {@link Subdivision#find}
 * algorithm to avoid construction costs or perform searches with a different epsilon.
 * 

 * The algorithm to incrementally construct a search structure for the trapezoidal map of a
 * planar subdivision was adapted from Mark de Berg et al., Computational Geometry
 * (3rd ed.), Springer-Verlag 2008, p.122-137. This implementation uses null half-edges and
 * {@link Double#MAX_VALUE} to indicate the unbounded face, rather than placing an actual
 * bounding rectangle around the {@link Subdivision}.
 * 
 * @author Christoph Nahr
 * @version 6.0.0
 */
public class SubdivisionSearch {

    // search graph containing nodes & trapezoids
    private Object _tree = new Trapezoid();

    /**
     * The maximum absolute difference at which two coordinates should be considered equal.
     * Equals either 1e-10 or the comparison {@link Subdivision#epsilon} of the associated
     * {@link #source}, whichever is greater.
     * 

     * The {@link SubdivisionSearch} algorithm always uses a positive {@link #epsilon} to
     * guard against {@link Subdivision#vertices} with infinitesimal coordinate differences
     * that might corrupt the search structure. If you encounter exceptions or incorrect
     * search results for a given {@link Subdivision}, try using a greater comparison
     * {@link Subdivision#epsilon} in its creation.
     */
    public final double epsilon;

    /**
     * The {@link Subdivision} for which the {@link SubdivisionSearch} graph was created.
     * Never {@code null}. The {@link SubdivisionSearch} graph is not updated to reflect
     * structural changes in the associated {@link Subdivision}. You must create a new
     * {@link SubdivisionSearch} to receive correct results for a changed {@link #source}.
     */
    public final Subdivision source;

    /**
     * Creates a {@link SubdivisionSearch} graph for the specified {@link Subdivision}.
     * The {@code ordered} parameter is intended for tests that require a known edge
     * insertion order. A random permutation is usually preferable, as the original
     * {@link Subdivision#edges} order can result in worst-case performance for the
     * {@link SubdivisionSearch} algorithm.
     * 
     * @param source the {@link Subdivision} to search
     * @param ordered {@code true} to insert the {@link Subdivision#edges} of {@code source}
     *                in their original order, {@code false} to apply a random permutation
     * @throws NullPointerException if {@code source} is {@code null}
     */
    public SubdivisionSearch(Subdivision source, boolean ordered) {
        this.source = source;
        this.epsilon = Math.max(1e-10, source.epsilon);

        final SubdivisionEdge[] edges = new SubdivisionEdge[source.edges().size() / 2];
        int index = 0;

        // find all twin half-edges with lexicographically smaller origin
        for (SubdivisionEdge edge: source.edges().values())
            if (PointDComparatorX.compareEpsilon(edge._origin, edge._twin._origin, epsilon) < 0)
                edges[index++] = edge;

        assert(index == edges.length);
        if (!ordered) Collections.shuffle(Arrays.asList(edges));

        for (SubdivisionEdge edge: edges)
            insertEdge(edge);
    }

    /**
     * Finds the {@link SubdivisionElement} at the specified {@link PointD}
     * coordinates within the associated {@link #source}.
     * Returns {@link SubdivisionElement#NULL_FACE} if {@code q} lies within the unbounded face
     * of the associated {@link #source}.
     * 

     * If {@code q} coincides with a {@link SubdivisionEdge}, {@code find} always returns the twin
     * {@link SubdivisionEdge} whose {@link SubdivisionEdge#origin} is lexicographically smaller
     * than its {@link SubdivisionEdge#destination}, according to {@link PointDComparatorX}.
     * 

     * {@code find} always uses the default {@link #epsilon} to determine whether {@code q}
     * coincides with an {@link SubdivisionElement#edge} or {@link SubdivisionElement#vertex}.
     * The {@link SubdivisionSearch} algorithm does not support a comparison epsilon that is
     * significantly different from that which was used to construct the search structure.
     * 
     * @param q the {@link PointD} coordinates to examine
     * @return the {@link SubdivisionElement} that coincides with {@code q}
     * @throws NullPointerException if {@code q} is {@code null}
     */
    public SubdivisionElement find(PointD q) {
        if (_tree instanceof Trapezoid)
            return SubdivisionElement.NULL_FACE;

        return ((Node) _tree).find(q);
    }

    /**
     * Returns a {@link String} that represents the entire {@link SubdivisionSearch} graph.
     * Implemented as a new method, rather than overriding {@link Object#toString},
     * because the returned {@link String} may be hundreds or thousands of lines long.
     * 
     * @return a {@link String} containing the {@link Object#toString} results for all nodes
     *         in the {@link SubdivisionSearch} graph, traversed in breadth-first order
     */
    public String format() {
        final StringBuilder builder = new StringBuilder();
        builder.append("Root: ");

        final Queue