View Javadoc

    1   /*
    2    * Licensed to the Apache Software Foundation (ASF) under one or more
    3    * contributor license agreements.  See the NOTICE file distributed with
    4    * this work for additional information regarding copyright ownership.
    5    * The ASF licenses this file to You under the Apache License, Version 2.0
    6    * (the "License"); you may not use this file except in compliance with
    7    * the License.  You may obtain a copy of the License at
    8    *
    9    *      http://www.apache.org/licenses/LICENSE-2.0
    10   *
    11   * Unless required by applicable law or agreed to in writing, software
    12   * distributed under the License is distributed on an "AS IS" BASIS,
    13   * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
    14   * See the License for the specific language governing permissions and
    15   * limitations under the License.
    16   */
    17  package org.apache.commons.geometry.euclidean.twod;
    18
    19  import java.util.Collections;
    20  import java.util.List;
    21
    22  import org.apache.commons.geometry.core.Transform;
    23  import org.apache.commons.geometry.core.partitioning.Hyperplane;
    24  import org.apache.commons.geometry.core.partitioning.HyperplaneConvexSubset;
    25  import org.apache.commons.geometry.core.partitioning.Split;
    26  import org.apache.commons.geometry.euclidean.oned.Interval;
    27
    28  /** Class representing a convex subset of a line in 2D Euclidean space. Instances
    29   * need not be finite, in which case the start or end point (or both) will be null.
    30   * Line segments and rays are examples of convex line subsets.
    31   * @see Lines
    32   */
    33  public abstract class LineConvexSubset extends LineSubset implements HyperplaneConvexSubset<Vector2D> {
    34
    35      /** Construct a new instance for the given line.
    36       * @param line line containing this line subset
    37       */
    38      LineConvexSubset(final Line line) {
    39          super(line);
    40      }
    41
    42      /** {@inheritDoc} */
    43      @Override
    44      public List<LineConvexSubset> toConvex() {
    45          return Collections.singletonList(this);
    46      }
    47
    48      /** {@inheritDoc}
    49       *
    50       * <p>This method always returns {@code false}.</p>
    51       */
    52      @Override
    53      public boolean isEmpty() {
    54          return false;
    55      }
    56
    57      /** Get the start point for the subset.
    58       * @return the start point for the subset, or null if no start point exists
    59       */
    60      public abstract Vector2D getStartPoint();
    61
    62      /** Get the 1D start location of the subset or {@link Double#NEGATIVE_INFINITY} if
    63       * no start location exists.
    64       * @return the 1D start location of the subset or {@link Double#NEGATIVE_INFINITY} if
    65       *      no start location exists.
    66       */
    67      public abstract double getSubspaceStart();
    68
    69      /** Get the end point for the subset.
    70       * @return the end point for the subset, or null if no end point exists.
    71       */
    72      public abstract Vector2D getEndPoint();
    73
    74      /** Get the 1D end location of the subset or {@link Double#POSITIVE_INFINITY} if
    75       * no end location exists.
    76       * @return the 1D end location of the subset or {@link Double#POSITIVE_INFINITY} if
    77       *      no end location exists
    78       */
    79      public abstract double getSubspaceEnd();
    80
    81      /** {@inheritDoc} */
    82      @Override
    83      public Interval getSubspaceRegion() {
    84          final double start = getSubspaceStart();
    85          final double end = getSubspaceEnd();
    86
    87          return Interval.of(start, end, getPrecision());
    88      }
    89
    90      /** Get the 1D interval for the region. This method is an alias for {@link #getSubspaceRegion()}.
    91       * @return the 1D interval for the region.
    92       */
    93      public Interval getInterval() {
    94          return getSubspaceRegion();
    95      }
    96
    97      /** {@inheritDoc} */
    98      @Override
    99      public Split<LineConvexSubset> split(final Hyperplane<Vector2D> splitter) {
    100         final Line thisLine = getLine();
    101         final Line splitterLine = (Line) splitter;
    102
    103         final Vector2D intersection = splitterLine.intersection(thisLine);
    104         if (intersection == null) {
    105             return getNonIntersectingSplitResult(splitterLine, this);
    106         }
    107         return splitOnIntersection(splitterLine, intersection);
    108     }
    109
    110     /** {@inheritDoc} */
    111     @Override
    112     public Vector2D closest(final Vector2D pt) {
    113         final Line line = getLine();
    114         final double abscissa = line.abscissa(pt);
    115
    116         return line.toSpace(closestAbscissa(abscissa));
    117     }
    118
    119     /** {@inheritDoc} */
    120     @Override
    121     public abstract LineConvexSubset transform(Transform<Vector2D> transform);
    122
    123     /** {@inheritDoc} */
    124     @Override
    125     public abstract LineConvexSubset reverse();
    126
    127     /** Get the closest value in the subspace region to the given abscissa.
    128      * @param abscissa input abscissa
    129      * @return the closest value in the subspace region to the given abscissa
    130      */
    131     abstract double closestAbscissa(double abscissa);
    132
    133     /** Split this instance using the given splitter line and intersection point.
    134      * @param splitter splitter line
    135      * @param intersection intersection point between the splitter line and the line
    136      *      for this instance
    137      * @return the result of splitting this instance with the given splitter line and intersection
    138      *      point
    139      */
    140     abstract Split<LineConvexSubset> splitOnIntersection(Line splitter, Vector2D intersection);
    141 }