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.spherical;
18  
19  import java.util.List;
20  
21  import org.apache.commons.geometry.core.RegionLocation;
22  import org.apache.commons.geometry.core.partitioning.Split;
23  import org.apache.commons.geometry.euclidean.threed.Vector3D;
24  import org.apache.commons.geometry.spherical.oned.AngularInterval;
25  import org.apache.commons.geometry.spherical.oned.Point1S;
26  import org.apache.commons.geometry.spherical.oned.RegionBSPTree1S;
27  import org.apache.commons.geometry.spherical.twod.GreatArcPath;
28  import org.apache.commons.geometry.spherical.twod.GreatCircle;
29  import org.apache.commons.geometry.spherical.twod.GreatCircles;
30  import org.apache.commons.geometry.spherical.twod.Point2S;
31  import org.apache.commons.geometry.spherical.twod.RegionBSPTree2S;
32  import org.apache.commons.numbers.angle.Angle;
33  import org.apache.commons.numbers.core.Precision;
34  import org.junit.jupiter.api.Assertions;
35  import org.junit.jupiter.api.Test;
36  
37  /** This class contains code listed as examples in the user guide and other documentation.
38   * If any portion of this code changes, the corresponding examples in the documentation <em>must</em> be updated.
39   */
40  class DocumentationExamplesTest {
41  
42      private static final double TEST_EPS = 1e-12;
43  
44      @Test
45      void testAngularIntervalExample() {
46          final Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-6);
47  
48          // create angular intervals of different sizes, one of size pi/2 and one of size 3pi/2
49          final AngularInterval a = AngularInterval.of(0, Angle.PI_OVER_TWO, precision);
50          final AngularInterval b = AngularInterval.of(Point1S.PI, Point1S.of(Angle.PI_OVER_TWO), precision);
51  
52          // test some points
53          a.contains(Point1S.of(0.25 * Math.PI)); // true
54          b.contains(Point1S.of(0.25 * Math.PI)); // true
55  
56          final RegionLocation aLocZero = a.classify(Point1S.ZERO); // RegionLocation.BOUNDARY
57          final RegionLocation bLocZero = b.classify(Point1S.ZERO); // RegionLocation.INSIDE
58  
59          // -------------------
60          Assertions.assertTrue(a.contains(Point1S.of(0.25 * Math.PI)));
61          Assertions.assertTrue(b.contains(Point1S.of(0.25 * Math.PI)));
62  
63          Assertions.assertEquals(RegionLocation.BOUNDARY, aLocZero);
64          Assertions.assertEquals(RegionLocation.INSIDE, bLocZero);
65      }
66  
67      @Test
68      void testRegionBSPTree1SExample() {
69          final Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-6);
70  
71          // create a region from the union of multiple angular intervals
72          final RegionBSPTree1S tree = RegionBSPTree1S.empty();
73          tree.add(AngularInterval.of(0, 0.25 * Math.PI, precision));
74          tree.add(AngularInterval.of(0.5 * Math.PI, Math.PI, precision));
75          tree.add(AngularInterval.of(0.75 * Math.PI, 1.5 * Math.PI, precision));
76  
77          // compute the region size in radians
78          final double size = tree.getSize(); // 1.25pi
79  
80          // convert back to intervals
81          final List<AngularInterval> intervals = tree.toIntervals(); //size = 2
82  
83          // ---------------
84          Assertions.assertEquals(1.25 * Math.PI, size, TEST_EPS);
85          Assertions.assertEquals(2, intervals.size());
86      }
87  
88      @Test
89      void testGreatCircleIntersectionExample() {
90          final Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-6);
91  
92          // create two great circles
93          final GreatCircle a = GreatCircles.fromPoints(Point2S.PLUS_I, Point2S.PLUS_K, precision);
94          final GreatCircle b = GreatCircles.fromPole(Vector3D.Unit.PLUS_Z, precision);
95  
96          // find the two intersection points of the great circles
97          final Point2S ptA = a.intersection(b); //(pi, pi/2)
98          final Point2S ptB = ptA.antipodal(); // (0, pi/2)
99  
100         // ----------------------
101         SphericalTestUtils.assertPointsEq(Point2S.MINUS_I, ptA, TEST_EPS);
102         SphericalTestUtils.assertPointsEq(Point2S.PLUS_I, ptB, TEST_EPS);
103     }
104 
105     @Test
106     void testRegionBSPTree2SExample() {
107         final Precision.DoubleEquivalence precision = Precision.doubleEquivalenceOfEpsilon(1e-6);
108 
109         // create a path outlining a quadrant triangle
110         final GreatArcPath path = GreatArcPath.builder(precision)
111                 .append(Point2S.PLUS_I)
112                 .append(Point2S.PLUS_J)
113                 .append(Point2S.PLUS_K)
114                 .build(true); // close the path with the starting path
115 
116         // convert to a region
117         final RegionBSPTree2S tree = path.toTree();
118 
119         // split in two through the centroid
120         final GreatCircle splitter = GreatCircles.fromPoints(tree.getCentroid(), Point2S.PLUS_K, precision);
121         final Split<RegionBSPTree2S> split = tree.split(splitter);
122 
123         // compute some properties for the minus side
124         final RegionBSPTree2S minus = split.getMinus();
125 
126         final double minusSize = minus.getSize(); // pi/4
127         final List<GreatArcPath> minusPaths = minus.getBoundaryPaths(); // size = 1
128 
129         // ---------------------
130         Assertions.assertEquals(Math.PI / 4, minusSize, TEST_EPS);
131         Assertions.assertEquals(1, minusPaths.size());
132     }
133 }