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  }