graphicarc.java

GEo 地理操作源代码

/**************************************************************************************************
 **
 ** $Id: GraphicArc.java,v 1.5 2004/05/12 00:34:44 crossley Exp $
 **
 ** $Source: /cvsroot/geoapi/src/org/opengis/go/display/primitive/GraphicArc.java,v $
 **
 ** Copyright (C) 2003 Open GIS Consortium, Inc. All Rights Reserved. http://www.opengis.org/Legal/
 **
 *************************************************************************************************/

package org.opengis.go.display.primitive;

import javax.units.Unit;

// J2SE direct dependencies
import java.util.ArrayList;
import java.util.List;

import org.opengis.go.spatial.PathType;
import org.opengis.spatialschema.geometry.DirectPosition;
import org.opengis.spatialschema.geometry.geometry.Conic;
import org.opengis.util.CodeList;
import org.opengis.util.SimpleEnumerationType;

/**
 * A <code>GraphicArc</code> represents a portion of an ellipse.
 * <P>
 * A <code>GraphicArc</code> is constructed from either an elliptic instance of
 * <code>Conic</code>, or the following graphical values:
 * <UL>
 * <LI>Its <code>center</code>, an instance of <code>DirectPosition</code>,
 * <LI>Its <code>width</code> and <code>height</code>, double precision values measured in length units from the <code>center</code>,
 * <LI>Its <code>rotation</code> angle, a double precision value,
 * <LI>Its arc <code>start</code> angle, a double precision value,
 * <LI>Its arc <code>end</code> angle, a double precision value.
 * </UL>
 * <P>
 * The geometric shape of <code>GraphicArc</code> can be modified via these parameters 
 * (the parameters are converted and passed to the underlying <code>Conic</code> object).
 * Similarly, if the underlying <code>Conic</code> changes shape but remains an ellipse, 
 * then the <code>GraphicArc</code> reflects that behavior 
 * (see <code>Graphic.refresh()</code>). If the <code>Conic</code> changes to a form 
 * other than an ellipse, then the behavior of <code>GraphicArc</code> is undefined.
 * <p>
 * The ellipse is oriented by centering it at the origin of a local Cartesian plane, 
 * with the major axis of the ellipse is aligned with the x-axis (abcissa).
 * Start and end points of the elliptic arc are measured positively as a counterclockwise angle
 * from the positive x-axis.
 * <p>
 * The rotation of the ellipse with respect to an external Coordinate Reference System is 
 * measured positively as a clockwise angle, starting from a reference line within the 
 * Coordinate Reference System and ending at the x-axis of the local Cartesian plane.
 * <p>
 * The external Coordinate Reference System is the Coordinate Reference System of the DirectPosition
 * correlating to the center of the ellipse.
 *
 * <img src="images/GraphicArc.gif">
 * 
 * If the width and height parameters are specified
 * in <code>com.dautelle.units.Length.Pixel</code>s, then a
 * <code>GraphicArc</code> shall retain shape and orientation regardless
 * of where it appears on the screen canvas.  If a
 * <code>setWidth</code> or <code>setHeight</code> method is called
 * with a conflicting type of <code>Unit</code>, then the
 * <code>GraphicArc</code> should convert its other parameter to the new
 * <code>Unit</code>s.  Thus, if a <code>GraphicArc </code> is defined in
 * pixels, and setWidth is called with a new value and the
 * <code>com.dautelle.units.Length.Meter</code> <code>Unit</code>,
 * then the <code>GraphicArc</code> should convert its height to meters as
 * well.
 * 
 * @author Open GIS Consortium, Inc.
 * @version $Revision: 1.5 $, $Date: 2004/05/12 00:34:44 $
 */
public interface GraphicArc extends Graphic {

    /**
     * Sets the geometry for this <code>GraphicArc</code>.
     * <p>
     * The geometry is oriented by centering the ellipse at the origin of a local Cartesian plane, 
     * with the major axis of the ellipse is aligned with the x-axis (abcissa).
     * Start and end points of the elliptic arc are measured positively as a counterclockwise angle
     * from the positive x-axis.
     * <p>
     * The rotation of the ellipse with respect to an external Coordinate Reference System is 
     * measured positively as a clockwise angle, starting from a reference line within the 
     * Coordinate Reference System and ending at the x-axis of the local Cartesian plane.
     * <p>
     * The geometric values are set on the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     * 
     * @param center the location of the centerpoint of the ellipse defining this <code>GraphicArc</code>.
     * @param width the length of the major axis of the ellipse defining this <code>GraphicArc</code>.
     * @param height the length of the minor axis of the ellipse defining this <code>GraphicArc</code>.
     * @param lengthUnit the unit of width and height.
     * @param rotation the rotation of the ellipse defining this <code>GraphicArc</code> with respect to the Coordinate Reference System of the centerpoint DirectPosition.
     * @param start the angle of starting point of the arc, drawn clockwise from the positive side of the major axis.
     * @param end the angle of the ending point of the arc, drawn clockwise from the positive side of the major axis.
     * @param angleUnit the unit of rotation.
     * @throws GeometryNotSupportedException if the width value is smaller than the height value is not an ellipse.
     */
    public void setArc(
        DirectPosition center,
        double width,
        double height,
        Unit lengthUnit,
        double rotation,
        double start,
        double end,
        Unit angleUnit);

    /**
     * Sets the center of the ellipse defining this <code>GraphicArc</code>. 
     * Value is set on the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     */
    public void setCenter(DirectPosition center);

    /**
     * Returns the center of the ellipse defining this <code>GraphicArc</code>.
     * Value is acquired from the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     */
    public DirectPosition getCenter();

    /**
     * Sets the size of the width axis 
     * of the ellipse defining this <code>GraphicArc</code>, in terms of the given <code>Unit</code>.
     * Value is set on the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     * @param width Size of the width axis.
     * @param unit the <code>Unit</code> of the width value.
     */
    public void setWidth(double width, Unit unit);

    /**
     * Returns the size of the width axis 
     * of the ellipse defining this <code>GraphicArc</code>, in terms of the given <code>Unit</code>.
     * Value is acquired from the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     * @param unit the <code>Unit</code> of the width value.
     * @return The size of the width axis of the arc.
     */
    public double getWidth(Unit unit);

    /**
     * Sets the size of the height axis 
     * of the ellipse defining this <code>GraphicArc</code>, in terms of the given <code>Unit</code>.
     * Value is set on the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     * @param height Size of the height axis.
     * @param unit the <code>Unit</code> of the height value.
     */
    public void setHeight(double height, Unit unit);

    /**
     * Returns the size of the height axis 
     * of the ellipse defining this <code>GraphicArc</code>, in terms of the given <code>Unit</code>.
     * Value is acquired from the underlying <code>Conic</code> geometry for this <code>Graphic</code>.
     * @param unit the <code>Unit</code> of the height value.
     * @return The size of the height axis of the arc.
     */
    public double getHeight(Unit unit);

    /**
     * Sets the geometry based on ISO 19107 <code>Conic</code> geometry for this <code>Graphic</code>. 
     * The <code>Conic</code> must be an ellipse (or a circle), otherwise 
     * <code>GeometryNotSupportedException</code> is thrown.
     * @param conic the elliptic conic for this <code>Graphic</code>.
     * @throws GeometryNotSupportedException if <code>Conic</code> is not an ellipse.
     */
    public void setConic(Conic conic) throws GeometryNotSupportedException;
    
    /**
     * Returns the ISO 19107 <code>Conic</code> geometry for this <code>Graphic</code>
     * @return the Conic representing this GraphicArc
     */
    public Conic getConic();

    /**
     * Sets the orientation for the width axis.  On a <code>Canvas</code>, this
     * might be the angle between the positive X axis and the width
     * axis of the arc. For a projected arc, this might be the angle
     * between due north and the width axis.
     * @param rotation  orientation of the arc.
     * @param unit the <code>Unit</code> for the angle value.
     */
    public void setRotation(double rotation, Unit unit);

    /**
     * Returns this <code>GraphicArc</code>'s orientation source.
     * @param unit the <code>Unit</code> for the angle value.
     * @return orientation of the arc.
     */
    public double getRotation(Unit unit);

    /**
     * Sets this <code>GraphicArc</code>'s start bearing. The arc is stroked
     * counter-clockwise from start to end.
     * @param start the start Orientation.
     * @param unit the <code>Unit</code> for the angle value.
     */
    public void setStart(double start, Unit unit);

    /**
     * Returns this <code>GraphicArc</code>'s start bearing. The arc is stroked
     * counter-clockwise from start to end.
     * @param unit the <code>Unit</code> for the angle value.
     * @return the arc start Orientation.