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.geometry.euclidean.threed.line;
018
019import java.util.List;
020
021/** Interface for objects that support linecast operations in Euclidean 3D space.
022 *
023 * <p>
024 * Linecasting is a process that takes a line or line convex subset and intersects it with
025 * the boundaries of a region. This is similar to
026 * <a href="https://en.wikipedia.org/wiki/Ray_casting">raycasting</a> used
027 * for collision detection with the exception that the intersecting element can be a
028 * line or line convex subset and not just a ray.
029 * </p>
030 */
031public interface Linecastable3D {
032
033    /** Intersect the given line against the boundaries in this instance, returning a
034     * list of all intersections in order of increasing distance along the line. An empty
035     * list is returned if no intersections are discovered.
036     * @param line line the line to intersect
037     * @return a list of computed intersections in order of increasing distance
038     *      along the line
039     */
040    default List<LinecastPoint3D> linecast(final Line3D line) {
041        return linecast(line.span());
042    }
043
044    /** Intersect the given line convex subset against the boundaries in this instance, returning
045     * a list of all intersections in order of increasing distance along the line. An empty list is
046     * returned if no intersections are discovered.
047     * @param subset line subset to intersect
048     * @return a list of computed intersections in order of increasing distance
049     *      along the line
050     */
051    List<LinecastPoint3D> linecast(LineConvexSubset3D subset);
052
053    /** Intersect the given line against the boundaries in this instance, returning the first
054     * intersection found when traveling in the direction of the line from infinity.
055     * @param line the line to intersect
056     * @return the first intersection found or null if no intersection
057     *      is found
058     */
059    default LinecastPoint3D linecastFirst(final Line3D line) {
060        return linecastFirst(line.span());
061    }
062
063    /** Intersect the given line convex subset against the boundaries in this instance, returning
064     * the first intersection found when traveling in the direction of the line subset from its
065     * start point.
066     * @param subset line subset to intersect
067     * @return the first intersection found or null if no intersection
068     *      is found
069     */
070    LinecastPoint3D linecastFirst(LineConvexSubset3D subset);
071}