001/*
002 *   GeomElement  -- Interface in common to all geometry elements.
003 *
004 *   Copyright (C) 2002-2015, 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 java.util.Map;
025import javax.measure.converter.ConversionException;
026import javax.measure.quantity.Length;
027import javax.measure.unit.Unit;
028import javax.swing.event.ChangeListener;
029import javolution.text.Text;
030import javolution.xml.XMLSerializable;
031
032/**
033 * Defines the interface in common to all geometry elements.
034 *
035 * <p> Modified by: Joseph A. Huwaldt</p>
036 *
037 * @author Joseph A. Huwaldt, Date: March 31, 2000
038 * @version August 31, 2015
039 *
040 * @param <T> The type of this geometry element.
041 */
042public interface GeomElement<T extends GeomElement> extends Cloneable, Comparable, XMLSerializable {
043
044    /**
045     * Return the unique ID number of this geometry element.
046     *
047     * @return The unique ID of this geometry element.
048     */
049    public long getID();
050
051    /**
052     * Return the name of this geometry element. If the name is not defined, then
053     * <code>null</code> is returned.
054     *
055     * @return The name of this geometry element.
056     */
057    public String getName();
058
059    /**
060     * Change the name of this geometry element to the specified name (may be
061     * <code>null</code> to clear the name and make it undefined).
062     *
063     * @param name The name of this geometry element.
064     */
065    public void setName(String name);
066
067    /**
068     * Returns the number of child-elements that make up this geometry element.
069     *
070     * @return The number of child-elements that make up this geometry element.
071     */
072    public int size();
073
074    /**
075     * Returns the text representation of this geometry element.
076     *
077     * @return The text representation of this geometry element.
078     */
079    public Text toText();
080
081    /**
082     * Returns the number of physical dimensions of this geometry element.
083     *
084     * @return The number of physical dimensions of this geometry element.
085     */
086    public int getPhyDimension();
087
088    /**
089     * Return a copy of this element converted to the specified number of physical
090     * dimensions. If the number of dimensions is greater than this element, then zeros
091     * are added to the additional dimensions. If the number of dimensions is less than
092     * this element, then the extra dimensions are simply dropped (truncated). If the new
093     * dimensions are the same as the dimension of this element, then this element is
094     * simply returned.
095     *
096     * @param newDim The dimension of the element to return.
097     * @return A copy of this geometry element converted to the new dimensions.
098     */
099    public T toDimension(int newDim);
100
101    /**
102     * Returns the number of parametric dimensions of this geometry element.
103     *
104     * @return The number of parametric dimensions of this geometry element.
105     */
106    public int getParDimension();
107
108    /**
109     * Return the coordinate point representing the minimum bounding box corner of this
110     * geometry element (e.g.: min X, min Y, min Z).
111     *
112     * @return The minimum bounding box coordinate for this geometry element.
113     */
114    public Point getBoundsMin();
115
116    /**
117     * Return the coordinate point representing the maximum bounding box corner of this
118     * geometry element (e.g.: max X, max Y, max Z).
119     *
120     * @return The maximum bounding box coordinate for this geometry element.
121     */
122    public Point getBoundsMax();
123
124    /**
125     * Returns the most extreme point, either minimum or maximum, in the specified
126     * coordinate direction on this geometry element. This is more accurate than
127     * <code>getBoundsMax</code> & <code>getBoundsMin</code>, but also typically takes
128     * longer to compute.
129     *
130     * @param dim An index indicating the dimension to find the min/max point for (0=X,
131     *            1=Y, 2=Z, etc).
132     * @param max Set to <code>true</code> to return the maximum value, <code>false</code>
133     *            to return the minimum.
134     * @param tol Fractional tolerance to refine the min/max point position to if
135     *            necessary.
136     * @return The point found on this element that is the min or max in the specified
137     *         coordinate direction.
138     * @see #getBoundsMin
139     * @see #getBoundsMax
140     */
141    public GeomPoint getLimitPoint(int dim, boolean max, double tol);
142
143    /**
144     * Return <code>true</code> if this GeomElement contains valid and finite numerical
145     * components. A value of <code>false</code> will be returned if any of the
146     * evaluations of this element are NaN or Inf.
147     *
148     * @return true if this geometry element contains valid and finite data.
149     */
150    public boolean isValid();
151
152    /**
153     * Returns the unit in which the geometry in this element are stated.
154     *
155     * @return The unit in which the geometry in this element are stated.
156     */
157    public Unit<Length> getUnit();
158
159    /**
160     * Returns the equivalent to this element but stated in the specified unit.
161     *
162     * @param unit the length unit of the element to be returned.
163     * @return an equivalent to this element but stated in the specified unit.
164     * @throws ConversionException if the the input unit is not a length unit.
165     */
166    public T to(Unit<Length> unit) throws ConversionException;
167
168    /**
169     * Returns a copy of this GeomElement instance
170     * {@link javolution.context.AllocatorContext allocated} by the calling thread
171     * (possibly on the stack).
172     *
173     * @return an identical and independent copy of this object.
174     */
175    public T copy();
176
177    /**
178     * Return a copy of this object with any transformations or subranges removed
179     * (applied).
180     *
181     * @return A copy of this object with any transformations removed (applied).
182     */
183    public T copyToReal();
184
185    /**
186     * Return any user defined object associated with this geometry element and the
187     * specified key. If there is no user data with the specified key, then
188     * <code>null</code> is returned.
189     *
190     * @param key the key whose associated value is to be returned or <code>null</code> if
191     *            the specified key could not be found.
192     * @return Any user defined data associated with this geometry and the specified key.
193     * @throws NullPointerException if <code>key</code> is <code>null</code>.
194     */
195    public Object getUserData(Object key);
196
197    /**
198     * Returns a new Map containing all the user objects associated with this geometry
199     * element.
200     *
201     * @return A new Map containing all the user objects associated with this geometry
202     *         element.
203     */
204    public Map getAllUserData();
205
206    /**
207     * Set the user defined object associated with this geometry element and the specified
208     * key. This can be used to store any type of information with a geometry element that
209     * could be useful.
210     *
211     * @param key   the key with which the specified value is to be associated.
212     * @param value the value to be associated with the specified key.
213     * @throws NullPointerException if the <code>key</code> is <code>null</code>.
214     */
215    public void putUserData(Object key, Object value);
216
217    /**
218     * Add all the user defined data in the supplied Map to this objects map of user
219     * defined data.
220     *
221     * @param data The Map of user defined data to be added to this object's map of user
222     *             defined data.
223     */
224    public void putAllUserData(Map data);
225
226    /**
227     * Removes the entry for the specified user object key if present.
228     *
229     * @param key the key whose mapping is to be removed from the map.
230     * @throws NullPointerException if the <code>key</code> is <code>null</code>.
231     */
232    public void removeUserData(Object key);
233
234    /**
235     * Add a listener that is notified of changes to the state of this element.
236     *
237     * @param listener The listener to be notified of changes to the state of this
238     *                 element.
239     */
240    public void addChangeListener(ChangeListener listener);
241
242    /**
243     * Remove a listener from receiving notifications of changes to the state of this
244     * element.
245     *
246     * @param listener The listener to be removed from those being notified of changes to
247     *                 the state of this element.
248     */
249    public void removeChangeListener(ChangeListener listener);
250
251}