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 }