001/*
002 *   ParametricGeometry  -- Interface for geometry elements that have parametric dimensions.
003 *
004 *   Copyright (C) 2009-2025, Joseph A. Huwaldt
005 *   All rights reserved.
006 *   
007 *   This library is free software; you can redistribute it and/or
008 *   modify it under the terms of the GNU Lesser General Public
009 *   License as published by the Free Software Foundation; either
010 *   version 2.1 of the License, or (at your option) any later version.
011 *   
012 *   This library is distributed in the hope that it will be useful,
013 *   but WITHOUT ANY WARRANTY; without even the implied warranty of
014 *   MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
015 *   Lesser General Public License for more details.
016 *
017 *   You should have received a copy of the GNU Lesser General Public License
018 *   along with this program; if not, write to the Free Software
019 *   Foundation, Inc., 59 Temple Place - Suite 330, Boston, MA  02111-1307, USA.
020 *   Or visit:  http://www.gnu.org/licenses/lgpl.html
021 */
022package geomss.geom;
023
024import jahuwaldt.js.param.Parameter;
025import java.util.List;
026import javax.measure.converter.ConversionException;
027import javax.measure.quantity.Length;
028import javax.measure.unit.Unit;
029
030/**
031 * Defines the interface for {@link GeomElement} objects that have parametric
032 * dimensions.
033 * 
034 * <p> Modified by: Joseph A. Huwaldt </p>
035 * 
036 * @author Joseph A. Huwaldt, Date: March 31, 2000
037 * @version February 17, 2025
038 *
039 * @param <T> The type of this parametric geometry object.
040 */
041public interface ParametricGeometry<T extends ParametricGeometry> extends GeomElement<T>, Transformable<T> {
042
043    /**
044     * Return a subrange point on the parametric geometry for the given
045     * parametric distance along the parametric geometry.
046     *
047     * @param s parametric distance to calculate a point for. Must be a
048     * 1-dimensional point with a value in the range 0 to 1.0.
049     * @return The subrange point
050     */
051    public SubrangePoint getPoint(GeomPoint s);
052
053    /**
054     * Calculate a point on the parametric geometry for the given parametric
055     * distance along the parametric geometry.
056     *
057     * @param s parametric distance to calculate a point for. Must be a
058     * 1-dimensional point with a value in the range 0 to 1.0.
059     * @return The calculated point.
060     */
061    public Point getRealPoint(GeomPoint s);
062
063    /**
064     * Calculate all the derivatives from <code>0</code> to <code>grade</code>
065     * with respect to parametric position(s) on a parametric object for the
066     * given parametric position on the object,
067     * <code>d^{grade}p(s)/d^{grade}s</code>.
068     * <p>
069     * Example:<br>
070     * 1st derivative (grade = 1), this returns <code>[p(s), dp(s)/ds]</code>;<br>
071     * 2nd derivative (grade = 2), this returns <code>[p(s), dp(s)/ds, d^2p(s)/d^2s]</code>; etc.
072     * </p>
073     *
074     * @param s parametric position to calculate the derivatives for. Must match
075     * the parametric dimension of this parametric surface and have each value
076     * in the range 0 to 1.0. Units are ignored.
077     * @param grade The maximum grade to calculate the derivatives for (1=1st
078     * derivative, 2=2nd derivative, etc)
079     * @return A list of lists of derivatives (one list for each parametric
080     * dimension). Each list contains derivatives up to the specified grade at
081     * the specified parametric position. Example: for a surface list element 0
082     * is the array of derivatives int the 1st parametric dimension (s), then
083     * 2nd list element is the array of derivatives in the 2nd parametric
084     * dimension (t).
085     * @throws IllegalArgumentException if the grade is &lt; 0.
086     */
087    public List<List<Vector<Length>>> getDerivatives(GeomPoint s, int grade);
088
089    /**
090     * Returns the closest point on this parametric object to the specified
091     * point.
092     *
093     * @param point The point to find the closest point on this parametric
094     * object to.
095     * @param tol Fractional tolerance (in parameter space) to refine the point
096     * position to.
097     * @return The point on this parametric object that is closest to the
098     * specified point.
099     */
100    public SubrangePoint getClosest(GeomPoint point, double tol);
101
102    /**
103     * Returns the farthest point on this parametric object from the specified
104     * point.
105     *
106     * @param point The point to find the farthest point on this parametric
107     * object from.
108     * @param tol Fractional tolerance (in parameter space) to refine the point
109     * position to.
110     * @return The {@link SubrangePoint} on this parametric object that is
111     * farthest from the specified point.
112     */
113    public SubrangePoint getFarthest(GeomPoint point, double tol);
114
115    /**
116     * Return <code>true</code> if this element is degenerate (i.e.: has length or area
117     * less than the specified tolerance).
118     *
119     * @param tol The tolerance for determining if this element is degenerate. May not be
120     *            null.
121     * @return true if this element is degenerate.
122     */
123    public boolean isDegenerate(Parameter<Length> tol);
124
125    /**
126     * Returns the equivalent to this parametric object but stated in the
127     * specified unit.
128     *
129     * @param unit the length unit of the parametric object to be returned.
130     * @return an equivalent to this parametric object but stated in the
131     * specified unit.
132     * @throws ConversionException if the the input unit is not a length unit.
133     */
134    @Override
135    public T to(Unit<Length> unit) throws ConversionException;
136
137    /**
138     * Return a copy of this parametric geometry converted to the specified
139     * number of physical dimensions. If the number of dimensions is greater
140     * than this element, then zeros are added to the additional dimensions. If
141     * the number of dimensions is less than this element, then the extra
142     * dimensions are simply dropped (truncated). If the new dimensions are the
143     * same as the dimension of this element, then this element is simply
144     * returned.
145     *
146     * @param newDim The dimension of the parametric geometry element to return.
147     * @return This parametric geometry element converted to the new dimensions.
148     */
149    @Override
150    public T toDimension(int newDim);
151
152    /**
153     * Returns a copy of this ParametricGeometry instance
154     * {@link javolution.context.AllocatorContext allocated} by the calling
155     * thread (possibly on the stack).
156     *
157     * @return an identical and independent copy of this object.
158     */
159    @Override
160    public T copy();
161}