001package icy.type.geom;
002
003import icy.type.point.Point3D;
004import icy.type.rectangle.Rectangle3D;
005
006/**
007 * The <code>Shape3D</code> interface provides definitions for objects
008 * that represent some form of 3D geometric Shape3D. Each <code>Shape3D</code> object provides callbacks to get the
009 * bounding box of the geometry, determine whether points or rectangles lie partly or entirely within the interior
010 * of the <code>Shape3D</code>.
011 * <p>
012 * <b>Definition of insideness:</b> A point is considered to lie inside a <code>Shape3D</code> if and only if:
013 * <ul>
014 * <li>it lies completely inside the<code>Shape3D</code> boundary <i>or</i>
015 * <li>it lies exactly on the <code>Shape3D</code> boundary.
016 * </ul>
017 * <p>
018 * The <code>contains</code> and <code>intersects</code> methods consider the interior of a <code>Shape3D</code> to be
019 * the area it encloses as if it were filled.
020 */
021public interface Shape3D
022{
023    /**
024     * Returns the bounding box of the <code>Shape3D</code>.
025     * Note that there is no guarantee that the returned {@link Rectangle3D} is the smallest bounding box that encloses
026     * the <code>Shape3D</code>, only that the <code>Shape3D</code> lies entirely within the indicated
027     * <code>Rectangle3D</code>.
028     * 
029     * @return an instance of <code>Rectangle3D</code> that is a
030     *         high-precision bounding box of the <code>Shape3D</code>.
031     */
032    public Rectangle3D getBounds();
033
034    /**
035     * Tests if the specified 3D coordinates are inside the boundary of the <code>Shape3D</code>.
036     * 
037     * @param x
038     *        the specified X coordinate to be tested
039     * @param y
040     *        the specified Y coordinate to be tested
041     * @param z
042     *        the specified Z coordinate to be tested
043     * @return <code>true</code> if the specified coordinates are inside
044     *         the <code>Shape3D</code> boundary; <code>false</code> otherwise.
045     */
046    public boolean contains(double x, double y, double z);
047
048    /**
049     * Tests if a specified {@link Point3D} is inside the boundary
050     * of the <code>Shape3D</code>.
051     * 
052     * @param p
053     *        the specified <code>Point3D</code> to be tested
054     * @return <code>true</code> if the specified <code>Point3D</code> is
055     *         inside the boundary of the <code>Shape3D</code>; <code>false</code> otherwise.
056     */
057    public boolean contains(Point3D p);
058
059    /**
060     * Tests if the interior of the <code>Shape3D</code> intersects the interior of a specified 3D rectangular area.
061     * The rectangular area is considered to intersect the <code>Shape3D</code> if any point is contained in both the
062     * interior of the <code>Shape3D</code> and the specified 3D rectangular area.
063     * <p>
064     * The {@code Shape3D.intersects()} method allows a {@code Shape3D} implementation to conservatively return
065     * {@code true} when:
066     * <ul>
067     * <li>there is a high probability that the 3D rectangular area and the <code>Shape3D</code> intersect, but
068     * <li>the calculations to accurately determine this intersection are prohibitively expensive.
069     * </ul>
070     * This means that for some {@code Shapes} this method might return {@code true} even though the 3D rectangular area
071     * does not intersect the {@code Shape3D}.
072     *
073     * @param x
074     *        the X coordinate of the closest-upper-left corner of the specified 3D rectangular area
075     * @param y
076     *        the Y coordinate of the closest-upper-left corner of the specified 3D rectangular area
077     * @param z
078     *        the Z coordinate of the closest-upper-left corner of the specified 3D rectangular area
079     * @param sizeX
080     *        the width of the specified 3D rectangular area
081     * @param sizeY
082     *        the height of the specified 3D rectangular area
083     * @param sizeZ
084     *        the depth of the specified 3D rectangular area
085     * @return <code>true</code> if the interior of the <code>Shape3D</code> and the interior of the 3D rectangular area
086     *         intersect, or are both highly likely to intersect and intersection calculations would be too expensive to
087     *         perform; <code>false</code> otherwise.
088     */
089    public boolean intersects(double x, double y, double z, double sizeX, double sizeY, double sizeZ);
090
091    /**
092     * Tests if the interior of the <code>Shape3D</code> intersects the
093     * interior of a specified <code>Rectangle3D</code>.
094     * The {@code Shape3D.intersects()} method allows a {@code Shape3D} implementation to conservatively return
095     * {@code true} when:
096     * <ul>
097     * <li>there is a high probability that the <code>Rectangle3D</code> and the <code>Shape3D</code> intersect, but
098     * <li>the calculations to accurately determine this intersection are prohibitively expensive.
099     * </ul>
100     * This means that for some {@code Shapes} this method might return {@code true} even though the {@code Rectangle3D}
101     * does not intersect the {@code Shape3D}.
102     *
103     * @param r
104     *        the specified <code>Rectangle3D</code>
105     * @return <code>true</code> if the interior of the <code>Shape3D</code> and the interior of the specified
106     *         <code>Rectangle3D</code> intersect, or are both highly likely to intersect and intersection calculations
107     *         would be too expensive to perform; <code>false</code> otherwise.
108     * @see #intersects(double, double, double, double, double, double)
109     */
110    public boolean intersects(Rectangle3D r);
111
112    /**
113     * Tests if the interior of the <code>Shape3D</code> entirely contains the specified 3D rectangular area. All
114     * coordinates that lie inside the 3D rectangular area must lie within the <code>Shape3D</code> for the entire
115     * 3D rectangular area to be considered contained within the <code>Shape3D</code>.
116     * <p>
117     * The {@code Shape3D.contains()} method allows a {@code Shape3D} implementation to conservatively return
118     * {@code false} when:
119     * <ul>
120     * <li>the <code>intersect</code> method returns <code>true</code> and
121     * <li>the calculations to determine whether or not the <code>Shape3D</code> entirely contains the 3D rectangular
122     * area are prohibitively expensive.
123     * </ul>
124     * This means that for some {@code Shapes} this method might return {@code false} even though the {@code Shape3D}
125     * contains the 3D rectangular area.
126     *
127     * @param x
128     *        the X coordinate of the closest-upper-left corner of the specified 3D rectangular area
129     * @param y
130     *        the Y coordinate of the closest-upper-left corner of the specified 3D rectangular area
131     * @param z
132     *        the Z coordinate of the closest-upper-left corner of the specified 3D rectangular area
133     * @param sizeX
134     *        the width of the specified 3D rectangular area
135     * @param sizeY
136     *        the height of the specified 3D rectangular area
137     * @param sizeZ
138     *        the depth of the specified 3D rectangular area
139     * @return <code>true</code> if the interior of the <code>Shape3D</code> entirely contains the specified rectangular
140     *         area; <code>false</code> otherwise or, if the <code>Shape3D</code> contains the 3D rectangular area and
141     *         the <code>intersects</code> method returns <code>true</code> and the containment calculations would be
142     *         too expensive to perform.
143     */
144    public boolean contains(double x, double y, double z, double sizeX, double sizeY, double sizeZ);
145
146    /**
147     * Tests if the interior of the <code>Shape3D</code> entirely contains the specified <code>Rectangle3D</code>.
148     * The {@code Shape3D.contains()} method allows a {@code Shape3D} implementation to conservatively return
149     * {@code false} when:
150     * <ul>
151     * <li>the <code>intersect</code> method returns <code>true</code> and
152     * <li>the calculations to determine whether or not the <code>Shape3D</code> entirely contains the
153     * <code>Rectangle3D</code> are prohibitively expensive.
154     * </ul>
155     * This means that for some {@code Shapes} this method might return {@code false} even though the {@code Shape3D}
156     * contains the {@code Rectangle3D}.
157     *
158     * @param r
159     *        The specified <code>Rectangle3D</code>
160     * @return <code>true</code> if the interior of the <code>Shape3D</code> entirely contains the
161     *         <code>Rectangle3D</code>; <code>false</code> otherwise or, if the <code>Shape3D</code> contains the
162     *         <code>Rectangle3D</code> and the <code>intersects</code> method returns <code>true</code> and the
163     *         containment calculations would be too expensive to perform.
164     * @see #contains(double, double, double, double, double, double)
165     */
166    public boolean contains(Rectangle3D r);
167}