Package jpicedt.graphic.model

Class PicEllipse

  • All Implemented Interfaces:
    Element, PicMultiCurveConvertable, PicObjectConstants, ActionFactory, CustomizerFactory
    Direct Known Subclasses:
    PicCircleFrom3Points
    public class PicEllipse
extends PicParallelogram
    Ellipse or arc, based on parallelogram
    The geometrical model of this ellipse (or its arc counterpart) is based on a parallelogram, yet is equivalent to an ellipse rotated around its center.

    In the following code documentation, we will be using two coordinate-systems, namely :

    • a so-called parallelogram basis, whose vectors are defined by the sides of the parallelogram. These correspond to fields l2rVec and b2tVec inherited from superclass.
    • an ellipse basis (also called canonical basis), whose vectors are defined by the great and small axes of the ellipse respectively.
    Arc angles may be expressed in either system, and this is indicated in code documentation when applicable. Prefix skew refers to the parallelogram basis, whereas rotated denotes angles measured in the ellipse basis. Since ellipse axes are generally not parallel to parallelogram sides, except in the event this parallelogram is a rectangle, both sets of angle DO obviously differ.

    In the parallelogram basis, arc is modelled by the following parametrized curve :
    Center + cos(t)*U+sin(t)*V,
    for t ranging from skewAngleStart to skewAngleEnd.

    Rotated angles are computed so that the arc of ellipse is obtained simply by rotating by "rotationAngle" (CCW) the arc of ellipse whose parametrization is Center+greatAxis*cos(t)*I+smallAxis*sin(t)*J where I,J is the ellipse canonical basis, and t varies between "rotatedAngleStart" and "rotatedAngleEnd". Note that this means that when small axis is negative, this parametrization goes CW and not CCW.

    [TODO] changes ALL internal angles to radian, and move conversion to setters/getters is user may want to enter degrees. [TODO] add a picture (in GIF or PNG format) to this documentation (as in AbstractCurve) to help end-users understand all these tricky things !

    Since:
    jPicEdt 1.4
    Version:
    $Id: PicEllipse.java,v 1.26.2.1 2007/09/02 11:56:26 reynal Exp $
    Author:
    Vincent Guirardel, Sylvain Reynal.

    • Field Detail

      • P_ANGLE_START

        public static final int P_ANGLE_START
        point marking start-of-arc
        See Also:
        Constant Field Values

      • P_ANGLE_END

        public static final int P_ANGLE_END
        point marking end-of-arc
        See Also:
        Constant Field Values

      • skewAngleStart

        protected double skewAngleStart
        Arc start- and end- angles in degrees as measured with respect to parallolegram's basis (see toParalleloBasisCoordinates() for details on how this basis is defined).

        To wind up shortly, let U and V denote unit-vectors defined by the sides of the parallelogram (these are actually given by "l2rVec" and "b2tVec" protected fields, yet immediately after computeParalleloBasis has been called), then the starting point of the arc is located at : Center+cos(skewAngleStart)*U+sin(skewAngleStart)*V.

        This value is closer to the user than rotatedAngleStart. [SR:je ne comprend pas cette phrase !!!]

        Moreover, arc is modelled by the following parametrized curve :
        Center + cos(t)*U+sin(t)*V,
        for t ranging from skewAngleStart to skewAngleEnd.

        We set skewAngleStart in (-180,180], and skewAngleEnd in (skewAngleStart,skewAngleStart+360]. This means that if one makes a mirror symmetry of the parallelogram and keeps the values of these "skew" angles unchanged, then we get the mirror image of the arc.
        We use degrees because user may enter a value. [SR:pending] On peut faire la conversion dans les setters correspondants (setAngleXXX). L'ideal est qd meme d'avoir la meme unite partout (en interne) pour ne pas s'emmeler les pedales.

        See Also:
        PicParallelogram.l2rVec, PicParallelogram.b2tVec

      • skewAngleEnd

        protected double skewAngleEnd
        See Also:
        skewAngleStart

      • rotationAngle

        protected double rotationAngle
        Angle in radians (CCW) between the great axis of the ellipse and the horizontal axis.

      • smallAxis

        protected double smallAxis
        Length of the small axis of the ellipse. May be negative, as this gives a more coherent behaviour under negative scaling in one direction. The sign is determined by the orientation of the parallelogram.

      • greatAxis

        protected double greatAxis
        Lengths of the great axis of the ellipse.

      • rotatedAngleStart

        protected double rotatedAngleStart
        Arc angles in degrees, as measured in the ellipse basis. These are computed from their "skew" counterparts, through a call to updateRotatedAngles, and are obviously identical with them if surrounding parallelogram is a rectangle.

        These angles may be used to build an appropriate Shape for this Element, by first creating an Arc2D from these angles, then rotating this shape by rotationAngle.

        We restrict values of rotatedAngleStart to (-180,180], and those of rotatedAngleEnd to (rotatedAngleStart,rotatedAngleStart+360].

      • rotatedAngleEnd

        protected double rotatedAngleEnd
        Arc angles in degrees, as measured in the ellipse basis. These are computed from their "skew" counterparts, through a call to updateRotatedAngles, and are obviously identical with them if surrounding parallelogram is a rectangle.

        These angles may be used to build an appropriate Shape for this Element, by first creating an Arc2D from these angles, then rotating this shape by rotationAngle.

        We restrict values of rotatedAngleStart to (-180,180], and those of rotatedAngleEnd to (rotatedAngleStart,rotatedAngleStart+360].

      • closure

        protected int closure
        closure type

    • Constructor Detail

      • PicEllipse

        public PicEllipse()
        Create a new PicEllipse, centered at (0,0), with a null radius. CLOSED is the default closure

      • PicEllipse

        public PicEllipse​(PicAttributeSet set)
        Create a new PicEllipse, centered at (0,0), with a null radius, and the given attribute set.

      • PicEllipse

        public PicEllipse​(int closure)
        Create a new PicEllipse, centered at (0,0), with a null radius, the given closure type.
        Parameters:
        closure - one of CHORD, PIE or OPEN.

      • PicEllipse

        public PicEllipse​(int closure,
                  PicAttributeSet set)
        Create a new PicEllipse, centered at (0,0), with a null radius, the given closure type, and the given attribute set.
        Parameters:
        closure - one of CHORD, PIE or OPEN.

      • PicEllipse

        public PicEllipse​(PicPoint p1,
                  PicPoint p2,
                  PicPoint p3,
                  int closure,
                  PicAttributeSet set)
        Create a new PicEllipse object using the 3 given points as 3 consecutive points of the surrounding parallelogram, and the given attribute set.
        Parameters:
        closure - one of CHORD, PIE or OPEN.

      • PicEllipse

        public PicEllipse​(PicPoint p1,
                  PicPoint p2,
                  PicPoint p3,
                  int closure)
        Create a new PicEllipse object using the 3 given points as 3 consecutive points of the surrounding parallelogram, and a default attribute set.
        Parameters:
        closure - one of CHORD, PIE or OPEN.

      • PicEllipse

        public PicEllipse​(PicEllipse ellipse)
        "cloning" constructor (to be used by clone())
        Parameters:
        The - PicEllipse object to clone

    • Method Detail

      • getName

        public java.lang.String getName()
        Return a localised string that represents this object's name
        Specified by:
        getName in interface Element
        Overrides:
        getName in class PicParallelogram
        Returns:
        a localised string that represents this object's name

      • setPoint

        public void setPoint​(int numPoint,
                     PicPoint pt,
                     EditPointConstraint constraint)
        Set the coordinate of the point indexed by "numPoint" to the given value. If point controls the parallelogram, calls the paralleogram setPoint method, and updates axis.
        Specified by:
        setPoint in interface Element
        Overrides:
        setPoint in class PicParallelogram
        Parameters:
        numPoint - one of P_TL, P_TR, P_BL, P_BR, SIDE_T, SIDE_B, SIDE_L, SIDE_R or P_CENTER.
        constraint - either null, DEFAULT, CENTER_FIXED or SQUARE

      • getPoint

        public PicPoint getPoint​(int numPoint,
                         PicPoint src)
        Return the user-controlled point having the given index. The general contract in Element is to return an IMMUTABLE instance of PicPoint, so that the only way to alter the geometry of this element is by calling the setPoint method.
        Specified by:
        getPoint in interface Element
        Overrides:
        getPoint in class PicParallelogram
        Parameters:
        numPoint - the point index, should be greater or equal to the value returned by getFirstPointIndex, and lower or equal to getLastPointIndex.
        Returns:
        the point indexed by numPoint ; if src is null, allocates a new PicPoint and return it, otherwise directly modifies src and returns it as well for convenience.

      • scale

        public void scale​(double ptOrgX,
                  double ptOrgY,
                  double sx,
                  double sy)
        Scale this object by (sx,sy) using (ptOrgX,ptOrgY) as the origin. This implementation simply apply a scaling transform to all specification-points. Note that sx and sy may be negative. This method eventually fires a changed-update event.
        Specified by:
        scale in interface Element
        Overrides:
        scale in class DefaultLeafElement

      • rotate

        public void rotate​(PicPoint ptOrg,
                   double angle)
        Rotate this Element by the given angle along the given point
        Specified by:
        rotate in interface Element
        Overrides:
        rotate in class PicParallelogram
        Parameters:
        angle - rotation angle in radians

      • shear

        public void shear​(PicPoint ptOrg,
                  double shx,
                  double shy)
        Shear this Element by the given params wrt to the given origin
        Specified by:
        shear in interface Element
        Overrides:
        shear in class PicParallelogram

      • getRotationAngle

        public double getRotationAngle()
        Return the rotation angle, ie the angle between the great axis of the ellipse and the horizontal axis.
        Returns:
        the rotation angle in radians (CCW)
        See Also:
        rotationAngle

      • getGreatAxisLength

        public double getGreatAxisLength()
        Return the length of the great-axis of this ellipse/arc.

      • getSmallAxisLength

        public double getSmallAxisLength()
        Return the length of the small-axis of this ellipse/arc.

      • setAngleStart

        public void setAngleStart​(double angleStart)
        Set the angle start, as measured in the parallelogram basis, then fire a changed-update. Arc always extends CCW from angle-start to angle-end, ie angle-extent is always positive.
        Parameters:
        The - starting angle of the arc, in degrees, counted COUNTERCLOCKWISE (aka trigonometric), and measured in the parallelogram basis, ie skewAngleStart.

      • getAngleStart

        public double getAngleStart()
        Returns skewAngleStart, ie the starting angle of the arc in degrees, measured in the frame defined by the parallelogram.

      • setAngleEnd

        public void setAngleEnd​(double angleEnd)
        Set the angle end, then fire a changed-update. Arc always extends CCW from angle-start to angle-end, ie angle-extent is always positive.
        Parameters:
        The - angle end of the arc, in degrees, measured in the frame defined by the parallelogram, ie skewAngleEnd.

      • getAngleEnd

        public double getAngleEnd()
        Returns skewAngleEnd, ie angle end of the arc in degrees, measured in the frame defined by the parallelogram. (value of skewAngleStart)

      • setAngleExtent

        public void setAngleExtent​(double angleExtent)
        Sets the angle extent, keeping the angle start fixed, then fire a changed update. If not positive, 360 is added to it.
        Parameters:
        Angular - extent of the arc, in degrees, counted COUNTERCLOCKWISE as measured in parallelogram basis.

      • getAngleExtent

        public double getAngleExtent()
        Returns the extent of the arc in degrees (CCW) as measured in the parallelogram basis. Note that this method returns 360 for a plain ellipse, not 0.
        Returns:
        an angle in (0,360]

      • getRotatedAngleStart

        public double getRotatedAngleStart()
        Return rotatedAngleStart, ie the angle start of the arc in degrees (CCW), as measured in the frame defined by the axes of the ellipse.

      • getRotatedAngleEnd

        public double getRotatedAngleEnd()
        Returns rotatedAngleEnd, ie the angle end of the arc in degrees as measured in the frame defined by the axes of the ellipse.

      • getRotatedAngleExtent

        public double getRotatedAngleExtent()
        Returns the angle extent of the arc in degrees as measured in the frame defined by the axes of the ellipse.

      • getArcType

        public int getArcType()
        Returns the closure type, ie one of CHORD, PIE or OPEN predefined constant fields.

      • getArcTypeAsString

        public java.lang.String getArcTypeAsString()
        Returns the closure type as a String, ie one of "chord", "pie" or "open"

      • setArcType

        public void setArcType​(int closure)
        Sets the closure type to one of CHORD, PIE or OPEN.

      • isFlat

        public boolean isFlat()
        Return true if this ellipse is flat.

      • isCircular

        public boolean isCircular()
        Returns TRUE if this ellipse is circular, ie if smallAxis==greatAxis.
        See Also:
        getSmallAxisLength()

      • isCircle

        public boolean isCircle()
        Deprecated.
        use isCircular() instead

      • isPlain

        public boolean isPlain()
        Return true if this PicEllipse is a plain ellipse, ie if angle extent equals 360.

      • isArc

        public boolean isArc()
        Returns true if this PicEllipse is an arc, ie if angle extent does not equl 360

      • isRotated

        public boolean isRotated()
        Return true if this PicEllipse has a null rotation angle along the x-axis

      • setPlain

        public void setPlain()
        Set angle parameters so that this ellipse is a plain ellipse.

      • isClosed

        public boolean isClosed()
        Returns whether this arc or ellipse is closed or not. This depends on the closure type, and this PicEllipse being plain or not.

      • _updateAxis

        protected void _updateAxis()
        Compute the axes of the ellipse (smallAxis, greatAxis), and the rotated angles in terms of the skew angles.

      • updateAxis

        protected void updateAxis()
        Compute the axes of the ellipse (smallAxis, greatAxis), and the rotated angles in terms of the skew angles.

      • updateRotatedAngles

        protected void updateRotatedAngles()
        Updates values of rotatedAngleStart and rotatedAngleEnd. Axes must be updated beforehands for this computation to be valid. if greatAxis==0 (implies smallAxis==0), we keep the old values [case of ellipse reduced to a point]. Flat case is handled by fromSkewToRotated.

      • getTangentAtAngleStart

        public PicPoint getTangentAtAngleStart​(PicVector pt)
        Utility for computing arrow direction.
        Parameters:
        pt - a preallocated PicPoint that get filled with the result ; a new one is allocated if pt==null
        Returns:
        a unit-1 vector tangent to the arc, at phi = start angle, pointing "outwardly"

      • getTangentAtAngleEnd

        public PicPoint getTangentAtAngleEnd​(PicVector pt)
        Utility for computing arrow direction.
        Parameters:
        pt - a preallocated PicPoint that get filled with the result ; a new one is allocated if pt==null
        Returns:
        a unit-1 vector tangent to the arc, at phi = end angle, pointing "outwardly"

      • toString

        public java.lang.String toString()
        Implementation of the Object.toString() method, used for debugging purpose
        Overrides:
        toString in class PicParallelogram
        Since:
        PicEdt 1.1.4