Package jpicedt.graphic.model

Class AbstractCurve

  • All Implemented Interfaces:
    Element, PicObjectConstants, ActionFactory
    Direct Known Subclasses:
    PicMultiCurve, PicPsCurve, PicSmoothPolygon
    public abstract class AbstractCurve
extends DefaultLeafElement
implements ActionFactory
    A curve made up of a concatenation of cubic bezier curves and straight lines, hereafter globally denoted as "segments". Straight lines are actually just bezier curves with control-points being identical with end-points. This curve may be either closed or not, and has a variable number of points. Segments may be added/inserted/deleted.

    There are two sort of points in this curve:

    • subdivision points, that is, endpoints of Bezier segments (indicated by SP(i), where i=segment_index, on picture above)
    • control-points of these Bezier segments (indicated by CP_first(i) and CP_second(i) for the first and the second control-point respectively of the ith-segment, on picture above)
    They are globally denoted as "Bezier points" and act as specification-points.

    Specification points

    Protected pts ArrayList inherited from DefaultLeafElement, which (according to the contract in the latter class) store specification points, contain the coordinates of all Bezier points with the following indexing scheme :
    • subdivision-points are indexed 0,3,6,9,12,...
    • control points are indexed 1,2 ; 4,5 ; 7,8 ; 10,11 ; ...
    These indices are globally denoted as "Bezier indices" throughout the code documentation.

    Arrays of specification-point coordinates are managed differently if the curve is open or close :

    • If the curve is open, the last element of the array is a subdivision point, namely the second curve's end-point. To sum up, pts[3i,3i+1,3i+2,3i+3] are the 1st endpoint, 2 control-points and last endpoint of the corresponding elementary Bezier curve resp., for i=[0..number of segments-1].
    • If the curve is closed, these arrays end up at the last control-point (e.g. 11 for a curve having 4 subdivision-points), hence for the last segment, pts[3i+3] is not defined. Yet in this case, getPBCBezierIndex() arranges for every index to be a valid index using periodic-boundary-conditions (PBC). This rule in turns applies to every method involving a point index.

    Subdivision-point vs. segment numbering scheme

    When used throughout the code documentation, the former expression means that 0,1,2 ... indices relate to the first, second, third,... subdivision point. This is indicated by SP(i) on picture above. Conversely, each segment is made up of three points (with the exception of the last curve's end-point if curve is open, which comprises a single segment), amongst which there is one subdivision point. Hence segment numbering ranges from 0 to getNumberOfSegments()-1 following the same numbering scheme as subdivision-points. Methods pointToSegmentIndex() and segmentToPointIndex() allow to translate between segment and bezier-point numbering schemes.

    Adding/removing points

    Methods splitSegment(), removeSubdivisionPoint(), lineTo() and curveTo() provide means to add/remove points to this curve. Abstract methods addPoint(),removePoint() and single-argument splitSegment(), whose implementation depends on the geometric "meaning" of user-controlled points, is left to subclassers.

    DrawingEvent's dispatching

    As a rule of thumb, any concrete subclass should post DrawingEvent's itself, where it thinks it has to, since none of the methods implemented here does it (this is aimed at reducing the burden for registered listeners which otherwise might -now and often- receive events twice).

    [SR:TODO] split curve into several pieces (aka old PicPolygon.convertToLines() method) ;
    [SR:TODO] join curves ;
    [SR:TODO] add resample() method allowing to delete m point out of n (useful for polygons generated from data files) [SR:BUG] setSmooth()/setSymmetric() => bug when neighbouring control-points are identical.
    Since:
    jpicedt 1.3.3
    Version:
    $Id: AbstractCurve.java,v 1.24.2.1 2007/09/02 11:56:20 reynal Exp $
    Author:
    Vincent Guirardel, Sylvain Reynal.

    • Field Detail

      • INVALID_POINT_INDEX

        public static final int INVALID_POINT_INDEX
        constant field for getPointType()
        See Also:
        Constant Field Values

      • FIRST_CURVE_END_POINT

        public static final int FIRST_CURVE_END_POINT
        constant field for getPointType()
        See Also:
        Constant Field Values

      • SUBDIVISION_POINT

        public static final int SUBDIVISION_POINT
        constant field for getPointType()
        See Also:
        Constant Field Values

      • FIRST_SEGMENT_CONTROL_POINT

        public static final int FIRST_SEGMENT_CONTROL_POINT
        constant field for getPointType()
        See Also:
        Constant Field Values

      • SECOND_SEGMENT_CONTROL_POINT

        public static final int SECOND_SEGMENT_CONTROL_POINT
        constant field for getPointType()
        See Also:
        Constant Field Values

      • LAST_CURVE_END_POINT

        public static final int LAST_CURVE_END_POINT
        constant field for getPointType()
        See Also:
        Constant Field Values

      • isClosed

        protected boolean isClosed
        tells whether this curve is closed of not

    • Constructor Detail

      • AbstractCurve

        public AbstractCurve()
        Creates a new empty open Abstract curve

      • AbstractCurve

        public AbstractCurve​(boolean closed)
        Creates a new empty Abstract curve
        Parameters:
        closed - whether the generated multi-curve will be closed or not

      • AbstractCurve

        public AbstractCurve​(boolean closed,
                     PicAttributeSet set)
        Creates a new empty Abstract curve with the given set of attributes
        Parameters:
        closed - whether the generated multi-curve will be closed or not
        set - attribute set to be bound to this curve

      • AbstractCurve

        public AbstractCurve​(int nbSegments,
                     boolean closed)
        Creates a new Abstract curve and allocates as many points as needed by the given number of segments. Each segment comprises three Bezier points (i.e. one end-point, and two control-points), yet if the curve is open, there is one more Bezier point, namely the last curve end-point.
        Parameters:
        nbSegments - nb of elementary lines or cubic Bezier curves ; if 0, this curve is reduced to a single point
        closed - whether this curve is closed or not
        Throws:
        java.lang.IllegalArgumentException - if nbSegments is negative

      • AbstractCurve

        public AbstractCurve​(int nbSegments,
                     boolean closed,
                     PicAttributeSet set)
        Creates a new Abstract curve with the given number of segments, and attaches the given attribute set to it.
        Parameters:
        nbSegments - nb of elementary lines or cubic Bezier curves
        set - attribute set to be bound to this element

      • AbstractCurve

        public AbstractCurve​(AbstractCurve curve)
        "cloning" constructor (to be used by clone())

    • Method Detail

      • getPointType

        public int getPointType​(int index)
        Returns whether the given point index relates to a curve's end-point, a subdivision point, a control point (in which case this method returns the rank of the control point inside the segment to which it belongs), or (if the curve is open) is an invalid point index.
        Note that if this curve is CLOSED, this method never returns FIRST_CURVE_END_POINT nor LAST_CURVE_END_POINT for that matter.
        Returns:
        a constant field, i.e. either SUBDIVISION_POINT, FIRST_SEGMENT_CONTROL_POINT, SECOND_SEGMENT_CONTROL_POINT, FIRST_CURVE_END_POINT, LAST_CURVE_END_POINT or INVALID_POINT_INDEX.

      • getPBCBezierIndex

        public int getPBCBezierIndex​(int bezierPtIdx)
        Convenience method for Periodic Boundary Condition (PBC) management when curve is CLOSED.

        If curve is CLOSED, returns the given index modulo the number of bezier points, i.e. an index guaranteed to lie b/w 0 and the number of bezier points minus one.
        Otherwise leaves unchanged.

        Parameters:
        bezierPtIdx - any integer, positive or not, greater than the number of bezier points or not, etc...
        Returns:
        a bezier-point index guaranteed to lie between 0 and the number of bezier points minus one.

      • getPBCSegmentIndex

        public int getPBCSegmentIndex​(int segmentIdx)
        Convenience method for Periodic Boundary Condition (PBC) management when curve is CLOSED.

        If curve is CLOSED, returns the given index modulo the number of segment, i.e. an index guaranteed to lie b/w 0 and the number of segments minus one.
        Otherwise leaves unchanged.

        Parameters:
        segmentIdx - any integer, positive or not, greater than the number of bezier points or not, etc...
        Returns:
        a segment index guaranteed to lie between 0 and the number of segments minus one.

      • getNearestSubdivisionPoint

        public int getNearestSubdivisionPoint​(int controlPtIdx)
        Returns the bezier-index of the nearest subdivision-point of the given control-point. The policy is to return the same index if the given point is NOT a control-point.

      • getAlternateControlPoint

        public int getAlternateControlPoint​(int controlPtIdx)
        Returns the bezier-index of the alternate control-point of the given control-point. The policy is to return the same index if the given point is NOT a control-point. Also note that the returned index is not guaranteed to be a valid index (there's no convincing way to test it here).

      • isControlPoint

        public boolean isControlPoint​(int index)
        Return whether the bezier-point with the given index is a control-point.

      • pointToSegmentIndex

        public int pointToSegmentIndex​(int pointIndex)
        Returns the index of the segment the given point belongs to.

      • segmentToPointIndex

        public int segmentToPointIndex​(int segmentIndex,
                               int pointType)
        Returns the index of the bezier-point belonging to the given segment, and having the given pointType.
        Parameters:
        pointType - one of SUBDIVISION_POINT, FIRST_SEGMENT_CONTROL_POINT or SECOND_SEGMENT_CONTROL_POINT. Other qualifiers are meaningless here, and act as the SUBDIVISION_POINT qualifier.

      • isValidBezierIndex

        public boolean isValidBezierIndex​(int pointIndex)
        Returns true iff the given bezier point index is a valid point index.
        See Also:
        getPointType(int)

      • isValidSegmentIndex

        public boolean isValidSegmentIndex​(int segIdx)
        Returns true iff the given segment index is a valid segment index. This is always true for closed curves.

      • hasValidSize

        protected final boolean hasValidSize()
        Return whether the current nb of specification points is valid, i.e. there is no incomplete segment. This may be used in conjunction with the "assert" keyword (as of JDK1.4) for debugging purpose.

      • getSpecificationPoint

        protected PicPoint getSpecificationPoint​(int index)
        Returns a reference on the specification point with the given index. This method is overriden from superclass so that, if the curve is closed, any index is a valid index using Periodic Boundary Conditions.
        Overrides:
        getSpecificationPoint in class DefaultLeafElement

      • setPoint

        public void setPoint​(int index,
                     PicPoint pt,
                     EditPointConstraint c)
        Set the coordinates of the Bezier point with the given index to the given location, but doesn't fire any DrawingEvent. If the curve is CLOSED, this methods arranges for any index to be a valid index by means of PBC's.
        Specified by:
        setPoint in interface Element
        Overrides:
        setPoint in class DefaultLeafElement
        Parameters:
        c - not used here

      • addPoint

        public abstract void addPoint​(PicPoint pt)
        Adds the given point to the end of this curve.

      • splitSegment

        public abstract int splitSegment​(int index,
                                 PicPoint pt)
        Split the segment having the given index.
        Returns:
        the index of the user-controlled point which got inserted, according to the indexing scheme of set/getPoint(). This may for instance allow a receiver to control the "new" segment shape by calling setPoint() with this index as a parameter w/o the burden of computing an exact point index (a thing that may depend on the particular implementation of this method).

      • removePoint

        public abstract void removePoint​(int index)
        Remove the point with the given index from this curve

      • curveTo

        public void curveTo​(PicPoint ptCtrl1,
                    PicPoint ptCtrl2,
                    PicPoint ptEnd)
        If this curve if OPEN and NON-EMPTY, adds the given points (2 control points and an endpoint) to the end of the curve.
        If the curve is closed, use splitSegment instead.
        Parameters:
        ptCtrl1 - first control point of the new Bezier segment
        ptCtrl2 - second control point of the new Bezier segment
        ptEnd - second end-point of the new Bezier segment

      • lineTo

        public void lineTo​(PicPoint pt)
        Adds a STRAIGHT segment to the end of this curve, i.e. control-points and subdivision-points are identical at each segment's end. This is a convenient call to curveTo.

        Note that this method does NOT fire any DrawingEvent.
        This method does nothing if the curve is EMPTY or CLOSED.

        Parameters:
        pt - The second end-point of the line to be added

      • splitSegment

        public int splitSegment​(int seg,
                        PicPoint ptleft,
                        PicPoint pt,
                        PicPoint ptright)
        Split a segment (either straight or curved) at a given point using two additionnal control points given as parameters.

        Implementation works as follow : parameters ptLeft and ptRight act as new control points, the original segment - labelled as [a,b,c,d] - being split up into two new segments, i.e. [a,b,ptleft,pt] and [pt,ptright,c,d]. These two segments inherit their straightness attribute from the original segment. This works for closed as well as open curves.

        Note that this method does NOT fire any DrawingEvent.

        Parameters:
        seg - index of segment to be split, i.e. 0,1,2,... for the 1st, 2nd, 3rd,... segment.
        ptleft - first new control-point
        pt - the point at which segment must be split (= new subdivision point)
        ptright - second new control-point
        Returns:
        the index of the subdivision-point which got inserted (see splitSegment(int,PicPoint) for details)

      • removeSubdivisionPoint

        public void removeSubdivisionPoint​(int subdivIndex)
        Remove a subdivision point from this curve, together with the two neighbouring control points. This shifts any ensuing points to the "left", i.e. reduces indices by one.
        Nothing is done if this curve has only one point. If both neighbouring segments had the same straightness value, it is inherited by the new segment. Otherwise, we set it to false.

        This method does NOT fire any DrawingEvent.

        Parameters:
        index - index of the subdivision point to be removed with respect to SUBDIVISION point numbering scheme, e.g. 0 for the first subdivision point (= first curve end-point), 1 for the second one (= bezier point with index "3"), etc... This is similar to the SEGMENT numbering scheme incidentally.
        Throws:
        an - IllegalArgumentException if the given index is not a valid subdivision point index, i.e. is greater than the nb of segments.

      • removeLastSubdivisionPoint

        public void removeLastSubdivisionPoint()
        Removes the last subdivision point. This is a convenience call to removeSubdivisionPoint.

      • getNumberOfSegments

        public int getNumberOfSegments()
        Returns the number of segments that make up this curve.

      • getNumberOfSubdivisionPoints

        public int getNumberOfSubdivisionPoints()
        Returns the number of subdivision points (including endpoints if the curve is open)

      • getIncomingTangent

        public PicVector getIncomingTangent​(int subdivIndex)
        Return a non-normalized vector tangent to the incoming segment (i.e., wrt the control-point that comes before the given subdivision point)
        Returns:
        a non-normalized vector, or null if the given subdivision point has no incoming tangent because it's the first point of an open curve

      • getOutgoingTangent

        public PicVector getOutgoingTangent​(int subdivIndex)
        Return a non-normalized vector tangent to the outcoming segment (i.e., wrt the control-point that comes after the given subdivision point)
        Returns:
        a non-normalized vector, or null if the given subdivision point has no outcoming tangent because it's the last point of an open curve

      • isStraight

        public boolean isStraight​(int segIndex)
        Returns whether the given segment is straight. This is carried out by checking whether control-points and subdivision-points are identical at each end of the given segment. Return false if this segment is reduced to a point.
        Parameters:
        segIndex - segment index with respect to the segment numbering scheme, that is, 0 for the first segment, etc...

      • isPolygon

        public boolean isPolygon()
        Return true if this curve is a polygon, ie has only straight segments

      • isSmooth

        public boolean isSmooth​(int subdivIndex)
        Check whether the two control points around the given subdivision point satisfy (up to 5%) the 2nd order smoothness criterion. If this curve is open, and subdivIndex relates to a curve's end-point, return true. If one of the neighbouring segment is straight, end-points are used instead of control-points.
        Parameters:
        subdivIndex - subdivision-point index, with respect to subdivision-point (SP) numbering scheme, i.e. 0,1,2,... for the 1st, 2nd, 3rd... subdivision point.

      • isSymmetric

        public boolean isSymmetric​(int subdivIndex)
        Check whether the control points around the given subdivision point satisfy (up to 5%) the symmetry criterion.
        Parameters:
        subdivIndex - subdivision-point index (with respect to subdivision-point numbering scheme), that is, 0,1,2,... for the 1st, 2nd, 3rd,... subdivision point.

      • setClosed

        public void setClosed​(boolean state)
        close or open this curve, either by opening the last segment if curve is closed, or by adding two control-points after the last segment if it is open.
        This methods doesn't fire any DrawingEvent.
        Parameters:
        state - The new closeness value

      • isClosed

        public boolean isClosed()
        Returns true if this curve is closed.

      • getShapeBounds2D

        public java.awt.geom.Rectangle2D getShapeBounds2D​(java.awt.geom.Rectangle2D r)
        Returns the the smallest rectangle enclosing the shape of this curve, as opposed to getBoundingBox which is defined as the smallest rectangle encompassing ALL specification points.
        Parameters:
        r - if null, gets allocated and returned for convenience

      • toString

        public java.lang.String toString()
        Returns a string for debugging purpose.
        Overrides:
        toString in class DefaultLeafElement

      • createActions

        public PEAction[] createActions​(ActionDispatcher actionDispatcher,
                                ActionLocalizer localizer,
                                HitInfo hi)
        Creates an array of Action's related to this object
        Specified by:
        createActions in interface ActionFactory
        Parameters:
        actionDispatcher - dispatches events to the proper PECanvas
        localizer - i18n localizer for PEAction's
        hi - a HitInfo containing information related to the mouse-event which triggered the popup menu.

      • createCustomizer

        public AbstractCustomizer createCustomizer()
        Returns a Customizer for geometry editing