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.math3.geometry.partitioning; 18 19 import org.apache.commons.math3.geometry.Space; 20 21 /** This interface is used to visit {@link BSPTree BSP tree} nodes. 22 23 * <p>Navigation through {@link BSPTree BSP trees} can be done using 24 * two different point of views:</p> 25 * <ul> 26 * <li> 27 * the first one is in a node-oriented way using the {@link 28 * BSPTree#getPlus}, {@link BSPTree#getMinus} and {@link 29 * BSPTree#getParent} methods. Terminal nodes without associated 30 * {@link SubHyperplane sub-hyperplanes} can be visited this way, 31 * there is no constraint in the visit order, and it is possible 32 * to visit either all nodes or only a subset of the nodes 33 * </li> 34 * <li> 35 * the second one is in a sub-hyperplane-oriented way using 36 * classes implementing this interface which obeys the visitor 37 * design pattern. The visit order is provided by the visitor as 38 * each node is first encountered. Each node is visited exactly 39 * once. 40 * </li> 41 * </ul> 42 43 * @param <S> Type of the space. 44 45 * @see BSPTree 46 * @see SubHyperplane 47 48 * @since 3.0 49 */ 50 public interface BSPTreeVisitor<S extends Space> { 51 52 /** Enumerate for visit order with respect to plus sub-tree, minus sub-tree and cut sub-hyperplane. */ 53 enum Order { 54 /** Indicator for visit order plus sub-tree, then minus sub-tree, 55 * and last cut sub-hyperplane. 56 */ 57 PLUS_MINUS_SUB, 58 59 /** Indicator for visit order plus sub-tree, then cut sub-hyperplane, 60 * and last minus sub-tree. 61 */ 62 PLUS_SUB_MINUS, 63 64 /** Indicator for visit order minus sub-tree, then plus sub-tree, 65 * and last cut sub-hyperplane. 66 */ 67 MINUS_PLUS_SUB, 68 69 /** Indicator for visit order minus sub-tree, then cut sub-hyperplane, 70 * and last plus sub-tree. 71 */ 72 MINUS_SUB_PLUS, 73 74 /** Indicator for visit order cut sub-hyperplane, then plus sub-tree, 75 * and last minus sub-tree. 76 */ 77 SUB_PLUS_MINUS, 78 79 /** Indicator for visit order cut sub-hyperplane, then minus sub-tree, 80 * and last plus sub-tree. 81 */ 82 SUB_MINUS_PLUS; 83 } 84 85 /** Determine the visit order for this node. 86 * <p>Before attempting to visit an internal node, this method is 87 * called to determine the desired ordering of the visit. It is 88 * guaranteed that this method will be called before {@link 89 * #visitInternalNode visitInternalNode} for a given node, it will be 90 * called exactly once for each internal node.</p> 91 * @param node BSP node guaranteed to have a non null cut sub-hyperplane 92 * @return desired visit order, must be one of 93 * {@link Order#PLUS_MINUS_SUB}, {@link Order#PLUS_SUB_MINUS}, 94 * {@link Order#MINUS_PLUS_SUB}, {@link Order#MINUS_SUB_PLUS}, 95 * {@link Order#SUB_PLUS_MINUS}, {@link Order#SUB_MINUS_PLUS} 96 */ visitOrder(BSPTree<S> node)97 Order visitOrder(BSPTree<S> node); 98 99 /** Visit a BSP tree node node having a non-null sub-hyperplane. 100 * <p>It is guaranteed that this method will be called after {@link 101 * #visitOrder visitOrder} has been called for a given node, 102 * it wil be called exactly once for each internal node.</p> 103 * @param node BSP node guaranteed to have a non null cut sub-hyperplane 104 * @see #visitLeafNode 105 */ visitInternalNode(BSPTree<S> node)106 void visitInternalNode(BSPTree<S> node); 107 108 /** Visit a leaf BSP tree node node having a null sub-hyperplane. 109 * @param node leaf BSP node having a null sub-hyperplane 110 * @see #visitInternalNode 111 */ visitLeafNode(BSPTree<S> node)112 void visitLeafNode(BSPTree<S> node); 113 114 } 115