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 */ 017package org.apache.commons.math3.geometry.partitioning; 018 019import 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 * @since 3.0 049 */ 050public interface BSPTreeVisitor<S extends Space> { 051 052 /** Enumerate for visit order with respect to plus sub-tree, minus sub-tree and cut sub-hyperplane. */ 053 enum Order { 054 /** Indicator for visit order plus sub-tree, then minus sub-tree, 055 * and last cut sub-hyperplane. 056 */ 057 PLUS_MINUS_SUB, 058 059 /** Indicator for visit order plus sub-tree, then cut sub-hyperplane, 060 * and last minus sub-tree. 061 */ 062 PLUS_SUB_MINUS, 063 064 /** Indicator for visit order minus sub-tree, then plus sub-tree, 065 * and last cut sub-hyperplane. 066 */ 067 MINUS_PLUS_SUB, 068 069 /** Indicator for visit order minus sub-tree, then cut sub-hyperplane, 070 * and last plus sub-tree. 071 */ 072 MINUS_SUB_PLUS, 073 074 /** Indicator for visit order cut sub-hyperplane, then plus sub-tree, 075 * and last minus sub-tree. 076 */ 077 SUB_PLUS_MINUS, 078 079 /** Indicator for visit order cut sub-hyperplane, then minus sub-tree, 080 * and last plus sub-tree. 081 */ 082 SUB_MINUS_PLUS; 083 } 084 085 /** Determine the visit order for this node. 086 * <p>Before attempting to visit an internal node, this method is 087 * called to determine the desired ordering of the visit. It is 088 * guaranteed that this method will be called before {@link 089 * #visitInternalNode visitInternalNode} for a given node, it will be 090 * called exactly once for each internal node.</p> 091 * @param node BSP node guaranteed to have a non null cut sub-hyperplane 092 * @return desired visit order, must be one of 093 * {@link Order#PLUS_MINUS_SUB}, {@link Order#PLUS_SUB_MINUS}, 094 * {@link Order#MINUS_PLUS_SUB}, {@link Order#MINUS_SUB_PLUS}, 095 * {@link Order#SUB_PLUS_MINUS}, {@link Order#SUB_MINUS_PLUS} 096 */ 097 Order visitOrder(BSPTree<S> node); 098 099 /** 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 */ 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 */ 112 void visitLeafNode(BSPTree<S> node); 113 114}