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.core;
    18
    19  import java.util.Collection;
    20  import java.util.List;
    21  import java.util.stream.Collectors;
    22
    23  /** This interface defines mappings between a space and one of its subspaces.
    24
    25   * <p>Subspaces are the lower-dimension subsets of a space. For example,
    26   * in an n-dimension space, the subspaces are the (n-1) dimension space,
    27   * the (n-2) dimension space, and so on. This interface can be used regardless
    28   * of the difference in number of dimensions between the space and the target
    29   * subspace. For example, a line in 3D Euclidean space can use this interface
    30   * to map directly from 3D Euclidean space to 1D Euclidean space (ie, the location
    31   * along the line).</p>
    32   *
    33   * @param <P> Point type defining the embedding space.
    34   * @param <S> Point type defining the embedded subspace.
    35   */
    36  public interface Embedding<P extends Point<P>, S extends Point<S>> {
    37
    38      /** Transform a space point into a subspace point.
    39       * @param pt n-dimension point of the space
    40       * @return lower-dimension point of the subspace corresponding to
    41       *      the specified space point
    42       * @see #toSpace
    43       */
    44      S toSubspace(P pt);
    45
    46      /** Transform a collection of space points into subspace points.
    47       * @param pts collection of n-dimension points to transform
    48       * @return collection of transformed lower-dimension points.
    49       * @see #toSubspace(Point)
    50       */
    51      default List<S> toSubspace(final Collection<P> pts) {
    52          return pts.stream().map(this::toSubspace).collect(Collectors.toList());
    53      }
    54
    55      /** Transform a subspace point into a space point.
    56       * @param pt lower-dimension point of the subspace
    57       * @return n-dimension point of the space corresponding to the
    58       *      specified subspace point
    59       * @see #toSubspace(Point)
    60       */
    61      P toSpace(S pt);
    62
    63      /** Transform a collection of subspace points into space points.
    64       * @param pts collection of lower-dimension points to transform
    65       * @return collection of transformed n-dimension points.
    66       * @see #toSpace(Point)
    67       */
    68      default List<P> toSpace(final Collection<S> pts) {
    69          return pts.stream().map(this::toSpace).collect(Collectors.toList());
    70      }
    71  }