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 }