001 /*
002 * Licensed to the Apache Software Foundation (ASF) under one or more
003 * contributor license agreements. See the NOTICE file distributed with
004 * this work for additional information regarding copyright ownership.
005 * The ASF licenses this file to You under the Apache License, Version 2.0
006 * (the "License"); you may not use this file except in compliance with
007 * the License. You may obtain a copy of the License at
008 *
009 * http://www.apache.org/licenses/LICENSE-2.0
010 *
011 * Unless required by applicable law or agreed to in writing, software
012 * distributed under the License is distributed on an "AS IS" BASIS,
013 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
014 * See the License for the specific language governing permissions and
015 * limitations under the License.
016 */
017 package org.apache.commons.math3.geometry.partitioning;
018
019 import org.apache.commons.math3.geometry.Space;
020
021 /** This interface is used to visit {@link BSPTree BSP tree} nodes.
022
023 * <p>Navigation through {@link BSPTree BSP trees} can be done using
024 * two different point of views:</p>
025 * <ul>
026 * <li>
027 * the first one is in a node-oriented way using the {@link
028 * BSPTree#getPlus}, {@link BSPTree#getMinus} and {@link
029 * BSPTree#getParent} methods. Terminal nodes without associated
030 * {@link SubHyperplane sub-hyperplanes} can be visited this way,
031 * there is no constraint in the visit order, and it is possible
032 * to visit either all nodes or only a subset of the nodes
033 * </li>
034 * <li>
035 * the second one is in a sub-hyperplane-oriented way using
036 * classes implementing this interface which obeys the visitor
037 * design pattern. The visit order is provided by the visitor as
038 * each node is first encountered. Each node is visited exactly
039 * once.
040 * </li>
041 * </ul>
042
043 * @param <S> Type of the space.
044
045 * @see BSPTree
046 * @see SubHyperplane
047
048 * @version $Id: BSPTreeVisitor.java 1416643 2012-12-03 19:37:14Z tn $
049 * @since 3.0
050 */
051 public interface BSPTreeVisitor<S extends Space> {
052
053 /** Enumerate for visit order with respect to plus sub-tree, minus sub-tree and cut sub-hyperplane. */
054 enum Order {
055 /** Indicator for visit order plus sub-tree, then minus sub-tree,
056 * and last cut sub-hyperplane.
057 */
058 PLUS_MINUS_SUB,
059
060 /** Indicator for visit order plus sub-tree, then cut sub-hyperplane,
061 * and last minus sub-tree.
062 */
063 PLUS_SUB_MINUS,
064
065 /** Indicator for visit order minus sub-tree, then plus sub-tree,
066 * and last cut sub-hyperplane.
067 */
068 MINUS_PLUS_SUB,
069
070 /** Indicator for visit order minus sub-tree, then cut sub-hyperplane,
071 * and last plus sub-tree.
072 */
073 MINUS_SUB_PLUS,
074
075 /** Indicator for visit order cut sub-hyperplane, then plus sub-tree,
076 * and last minus sub-tree.
077 */
078 SUB_PLUS_MINUS,
079
080 /** Indicator for visit order cut sub-hyperplane, then minus sub-tree,
081 * and last plus sub-tree.
082 */
083 SUB_MINUS_PLUS;
084 }
085
086 /** Determine the visit order for this node.
087 * <p>Before attempting to visit an internal node, this method is
088 * called to determine the desired ordering of the visit. It is
089 * guaranteed that this method will be called before {@link
090 * #visitInternalNode visitInternalNode} for a given node, it will be
091 * called exactly once for each internal node.</p>
092 * @param node BSP node guaranteed to have a non null cut sub-hyperplane
093 * @return desired visit order, must be one of
094 * {@link Order#PLUS_MINUS_SUB}, {@link Order#PLUS_SUB_MINUS},
095 * {@link Order#MINUS_PLUS_SUB}, {@link Order#MINUS_SUB_PLUS},
096 * {@link Order#SUB_PLUS_MINUS}, {@link Order#SUB_MINUS_PLUS}
097 */
098 Order visitOrder(BSPTree<S> node);
099
100 /** Visit a BSP tree node node having a non-null sub-hyperplane.
101 * <p>It is guaranteed that this method will be called after {@link
102 * #visitOrder visitOrder} has been called for a given node,
103 * it wil be called exactly once for each internal node.</p>
104 * @param node BSP node guaranteed to have a non null cut sub-hyperplane
105 * @see #visitLeafNode
106 */
107 void visitInternalNode(BSPTree<S> node);
108
109 /** Visit a leaf BSP tree node node having a null sub-hyperplane.
110 * @param node leaf BSP node having a null sub-hyperplane
111 * @see #visitInternalNode
112 */
113 void visitLeafNode(BSPTree<S> node);
114
115 }