    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    }