/*
 * @(#)AutomaticShape.java    2.4.0   2 May 2006
 *
 * Copyright 2006
 * College of Computer and Information Science
 * Northeastern University
 * Boston, MA  02115
 *
 * The Java Power Tools software may be used for educational
 * purposes as long as this copyright notice is retained intact
 * at the top of all source files.
 *
 * To discuss possible commercial use of this software, 
 * contact Richard Rasala at Northeastern University, 
 * College of Computer and Information Science,
 * 617-373-2462 or rasala@ccs.neu.edu.
 *
 * The Java Power Tools software has been designed and built
 * in collaboration with Viera Proulx and Jeff Raab.
 *
 * Should this software be modified, the words "Modified from 
 * Original" must be included as a comment below this notice.
 *
 * All publication rights are retained.  This software or its 
 * documentation may not be published in any media either
 * in whole or in part without explicit permission.
 *
 * This software was created with support from Northeastern 
 * University and from NSF grant DUE-9950829.
 */

package edu.neu.ccs.gui;

import edu.neu.ccs.util.*;

import java.awt.*;
import java.awt.geom.*;
import java.beans.*;

/**
 * <p>Class <code>AutomaticShape</code> implements a
 * <code>BaseVertexShape</code> in which the tangent array is always
 * automatically computed from the vertex array and other settings
 * using a <code>Tangent.Strategy</code> object.</p>
 *
 * <p>The default tangent strategy produces tangents for Bezier curves in
 * which the first and second derivatives of the curve are continuous at
 * each vertex.  This strategy is described in the article:</p>
 *
 * <p>Richard Rasala, Explicit Cubic Spline Interpolation Formulas, in
 * Andrew S. Glassner, Graphics Gems, Academic Press, 1990, 579-584.</p>
 * 
 * <p>The derived class <code>AutomaticCurve</code> was introduced in
 * 2.4.0 to fix the path strategy to be <code>Path.BEZIER_CUBIC</code>
 * since that is the most common case.</p>
 *
 * <p>To define a shape in which the tangent array varies independently
 * of the vertex array, use the class <code>TweakableShape</code>.</p>
 *
 * <p>The internal tangent array will be maintained as non-<code>null</code>
 * as a byproduct of computing tangents via a tangent strategy.</p>
 *
 * <p>To efficiently define a polygonal shape that does not use tangents,
 * use either <code>PolygonShape</code> or <code>PolygonDotsShape</code>.</p>
 *
 * @author  Richard Rasala
 * @version 2.4.0
 * @since   2.3
 */
public class AutomaticShape
    extends BaseVertexShape
{
    
    /** Bound property name to set the tangent strategy. */
    public static final String SET_TANGENT_STRATEGY = "set.tangent.strategy";
    
    /** Bound property name to set one or both end tangents. */
    public static final String SET_END_TANGENT      = "set.end.tangent";
    
    
    /** The tangent strategy. */
    private Tangent.Strategy tangentstrategy = Tangent.bezierStrategy();
    
    /** The end tangent data. */
    private float[][] endTangent = null;
    
    
    /**
     * <p>The default constructor with an empty shape.</p>
     *
     * <p>The default settings are as follows:</p>
     *
     * <ul>
     *   <li>Vertex data:      <code>new float[0][2]</code></li>
     *   <li>End tangent data: <code>null</code></li>
     *   <li>Tangent strategy: <code>Tangent.bezierStrategy()</code></li>
     *   <li>Path strategy:    <code>Path.BEZIER_CUBIC</code></li>
     *   <li>Closure mode:     <code>ClosureMode.CLOSED</code></li>
     *   <li>Winding rule:     <code>WindingRule.WIND_NON_ZERO</code>.</li>
     * </ul>
     */
    public AutomaticShape() {
        this(null, null, null, null, null, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * @param vertex the vertex data
     */
    public AutomaticShape(float[][] vertex) {
        this(vertex, null, null, null, null, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data
     * and the given end tangent data.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * @param vertex     the vertex data
     * @param endTangent the end tangent data
     */
    public AutomaticShape(float[][] vertex, float[][] endTangent) {
        this(vertex, endTangent, null, null, null, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data,
     * the given end tangent data,
     * and the given tangent strategy.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * @param vertex          the vertex data
     * @param endTangent      the end tangent data
     * @param tangentstrategy the tangent strategy
     */
    public AutomaticShape
        (float[][]        vertex,
         float[][]        endTangent,
         Tangent.Strategy tangentstrategy)
    {
        this(vertex, endTangent, tangentstrategy, null, null, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data,
     * the given end tangent data,
     * the given tangent strategy,
     * and the given path strategy.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * @param vertex          the vertex data
     * @param endTangent      the end tangent data
     * @param tangentstrategy the tangent strategy
     * @param pathstrategy    the path strategy
     */
    public AutomaticShape
        (float[][]        vertex,
         float[][]        endTangent,
         Tangent.Strategy tangentstrategy,
         Path.Strategy    pathstrategy)
    {
        this(vertex, endTangent, tangentstrategy, pathstrategy, null, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data,
     * the given end tangent data,
     * the given tangent strategy,
     * the given path strategy,
     * and the given closure mode.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * @param vertex          the vertex data
     * @param endTangent      the end tangent data
     * @param tangentstrategy the tangent strategy
     * @param pathstrategy    the path strategy
     * @param closuremode     the closure mode
     */
    public AutomaticShape
        (float[][]        vertex,
         float[][]        endTangent,
         Tangent.Strategy tangentstrategy,
         Path.Strategy    pathstrategy,
         ClosureMode      closuremode)
    {
        this(vertex, endTangent, tangentstrategy, pathstrategy, closuremode, null);
    }
    
    
    /**
     * <p>The constructor with the given vertex data,
     * the given end tangent data,
     * the given tangent strategy,
     * the given path strategy,
     * the given closure mode,
     * and the given winding rule.</p>
     *
     * <p>Preconditions:</p>
     * <ul>
     *   <li>The given vertex array is either <code>null</code> or
     *       <code>float[N][2]</code> for some N.</li>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given vertex array is <code>null</code> then the
     * internal vertex array is set to <code>float[0][2]</code>.</p>
     * 
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * @param vertex          the vertex data
     * @param endTangent      the end tangent data
     * @param tangentstrategy the tangent strategy
     * @param pathstrategy    the path strategy
     * @param closuremode     the closure mode
     * @param windingrule     the winding rule
     */
    public AutomaticShape
        (float[][]        vertex,
         float[][]        endTangent,
         Tangent.Strategy tangentstrategy,
         Path.Strategy    pathstrategy,
         ClosureMode      closuremode,
         WindingRule      windingrule)
    {
        // initialize internal vertex data to defaults
        this.vertex  = new float[0][2];
        
        // initialize a null path strategy to BEZIER_CUBIC
        if (pathstrategy == null)
            pathstrategy = Path.BEZIER_CUBIC;
        
        setTangentStrategy(tangentstrategy);
        setPathStrategy(pathstrategy);
        setClosureMode(closuremode);
        setWindingRule(windingrule);
        setEndTangentData(endTangent);
        setVertexData(vertex);
        
        makePath();
    }
    
    
    /**
     * Returns true if the internal end tangent data is <code>null</code>.
     */
    public final boolean isEndTangentNull() {
        return endTangent == null;
    }
    
    
    /**
     * <p>Sets the end tangent data of the shape using a 2-by-2 array
     * of single precision numbers and makes a new path.</p>
     *
     * <p>Sets the tangents to be used when the shape is displayed as
     * an open curve.</p>
     *
     * <p>Precondition:</p>
     * <ul>
     *   <li>The given end tangent array is either <code>null</code>
     *       or <code>float[2][2]</code>.</li>
     * </ul>
     *
     * <p>If the given end tangent array is <code>null</code> then
     * an open curve is rendered with the same end tangents as are
     * computed automatically for the corresponding closed curve.</p>
     *
     * <p>Does nothing if the precondition fails.</p>
     *
     * <p>Fires property change: SET_END_TANGENT.</p>
     * 
     * @param endTangent the end tangent data to set
     */
    public final void setEndTangentData(float[][] endTangent) {
        if (endTangent == null) {
            this.endTangent = null;
        }
        else {
            if (! (FloatArray.checkArray(endTangent, 2) && endTangent.length == 2))
                return;
            
            this.endTangent = FloatArray.deepclone(endTangent);
        }
        
        makePath();
        
        firePropertyChange(SET_END_TANGENT, null, null);
    }
    
    
    /**
     * <p>Returns a clone of the end tangent array.</p>
     *
     * <p>The returned array will either be <code>null</code> or
     * have the form <code>float[2][2]</code>.</p>
     *
     * <p>You may use the method <code>isEndTangentNull()</code> to
     * test if the internal end tangent array is <code>null</code>
     * without needing to ask for the data.</p>
     *
     * @return a clone of the end tangent array
     */
    public final float[][] getEndTangentData() {
        return FloatArray.deepclone(endTangent);
    }
    
    
    /**
     * <p>Sets the end tangent at the given index 0 or 1 to the given
     * delta coordinates dx, dy and makes a new path.</p>
     *
     * <p>Does nothing if the index is not 0 or 1.</p>
     *
     * <p>If the current end tangent array is <code>null</code>, then
     * this array will be set to new <code>float[2][2]</code> before
     * setting the delta value.</p>
     *
     * <p>Fires property change: SET_END_TANGENT.</p>
     *
     * @param index the end tangent index
     * @param dx the new x-coordinate for the end tangent
     * @param dy the new y-coordinate for the end tangent
     */
    public final void setEndTangent(int index, float dx, float dy) {
        if ((index < 0) || (index > 1))
            return;
        
        if (endTangent == null) {
            endTangent = new float[2][2];
        }
        
        endTangent[index][0] = dx;
        endTangent[index][1] = dy;
        
        makePath();
        
        firePropertyChange(SET_END_TANGENT, null, null);
    }
    
    
    /**
     * <p>Sets the end tangent at the given index 0 or 1 to the given
     * delta and makes a new path.</p>
     *
     * <p>Does nothing if the index is not 0 or 1.</p>
     *
     * <p>Does nothing if delta is not <code>float[2]</code>.</p>
     *
     * <p>If the current end tangent array is <code>null</code>, then
     * this array will be set to new <code>float[2][2]</code> before
     * setting the delta value.</p>
     *
     * <p>Fires property change: SET_END_TANGENT.</p>
     *
     * @param index the vertex index
     * @param delta the new delta for the vertex at the given index
     */
    public final void setEndTangent(int index, float[] delta) {
        if ((delta == null) || (delta.length != 2))
            return;
        
        setEndTangent(index, delta[0], delta[1]);
    }
    
    
    /**
     * <p>Returns the x-coordinate of the end tangent data if the given
     * index is 0 or 1 or returns 0 if the index is out of bounds or
     * if the end tangent data is <code>null</code>.</p>
     *
     * <p>This method should only be used if the caller knows that the
     * internal end tangent data is non-<code>null</code>.  This may
     * be tested using <code>isTangentNull()</code>.</p>
     *
     * @param index the index of the end tangent (0 or 1)
     */
    public final float getEndTX(int index) {
        if (endTangent == null)
            return 0;
        
        if ((index < 0) || (index > 1))
            return 0;
        
        return endTangent[index][0];
    }
    
    
    /**
     * <p>Returns the y-coordinate of the end tangent data if the given
     * index is 0 or 1 or returns 0 if the index is out of bounds or
     * if the end tangent data is <code>null</code>.</p>
     *
     * <p>This method should only be used if the caller knows that the
     * internal end tangent data is non-<code>null</code>.  This may
     * be tested using <code>isTangentNull()</code>.</p>
     *
     * @param index the index of the end tangent (0 or 1)
     */
    public final float getEndTY(int index) {
        if (endTangent == null)
            return 0;
        
        if ((index < 0) || (index > 1))
            return 0;
        
        return endTangent[index][1];
    }
    
    
    /**
     * <p>Returns a copy of the end tangent at the given index which
     * should be 0 or 1.</p>
     *
     * <p>More precisely, if the index is 0 or 1 and the end tangent
     * array is non-<code>null</code>, then returns:</p>
     *
     * <pre>  new float[] { getEndTX(index), getEndTY(index) }</pre>
     *
     * <p>Otherwise, returns <code>null</code>.</p>
     *
     * <p>This methods returns <code>null</code> if the end tangent
     * array is <code>null</code> because that signifies a different
     * rendering behavior for the shape.  A <code>null</code> end
     * tangent array does not signify a default of 0 for the end
     * tangents.</p>
     *
     * @param index the index of the end tangent (0 or 1)
     */
    public final float[] getEndTangent(int index) {
        if (endTangent == null)
            return null;
        
        if ((index < 0) || (index > 1))
            return null;
        
        return new float[] { getEndTX(index), getEndTY(index) };
    }
    
    
    /**
     * <p>Sets the end tangent at the given index 0 or 1 assuming the
     * given coordinates (x,y) are the coordinates of the associated
     * control point and then makes a new path.</p>
     *
     * <p>Does nothing if:</p>
     *
     * <ul>
     *   <li>The given index is not 0 or 1.</li>
     *   <li>The internal vertex array has length N less than 2.</li>
     * </ul>
     *
     * <p>If the current end tangent array is <code>null</code>, then
     * this array will be set to new <code>float[2][2]</code> before
     * setting the delta value.</p>
     *
     * <p>For index = 0, computes the end tangent as:</p>
     *
     * <pre>  (x,y) - getVertex(0)</pre>
     *
     * <p>For index = 1, computes the end tangent as:</p>
     *
     * <pre>  getVertex(N-1) - (x,y)</pre>
     *
     * <p>Fires property change: SET_END_TANGENT.</p>
     *
     * @param index the end tangent index
     * @param x the x-coordinate for the control
     * @param y the y-coordinate for the control
     */
    public final void setEndTangentViaControl(int index, float x, float y) {
        if ((index < 0) || (index > 1))
            return;
        
        int N = vertex.length;
        
        if (N < 2)
            return;
        
        int M = N - 1;
        
        if (endTangent == null) {
            endTangent = new float[2][2];
        }
        
        if (index == 0) {
            endTangent[0][0] = x - vertex[0][0];
            endTangent[0][1] = y - vertex[0][1];
        }
        else {
            endTangent[1][0] = vertex[M][0] - x;
            endTangent[1][1] = vertex[M][1] - y;
        }
        
        makePath();
        
        firePropertyChange(SET_END_TANGENT, null, null);
    }
    
    
    /**
     * <p>Sets the end tangent at the given index 0 or 1 assuming the
     * given control is an associated control point and then makes a
     * new path.</p>
     *
     * <p>Does nothing if:</p>
     *
     * <ul>
     *   <li>The given index is not 0 or 1.</li>
     *   <li>The internal vertex array has length N less than 2.</li>
     * </ul>
     *
     * <p>If the current end tangent array is <code>null</code>, then
     * this array will be set to new <code>float[2][2]</code> before
     * setting the delta value.</p>
     *
     * <p>For index = 0, computes the end tangent as:</p>
     *
     * <pre>  control - getVertex(0)</pre>
     *
     * <p>For index = 1, computes the end tangent as:</p>
     *
     * <pre>  getVertex(N-1) - control</pre>
     *
     * <p>Fires property change: SET_END_TANGENT.</p>
     *
     * @param index   the end tangent index
     * @param control the control point
     */
    public final void setEndTangentViaControl(int index, float[] control) {
        if ((control == null) || (control.length != 2))
            return;
        
        setEndTangentViaControl(index, control[0], control[1]);
    }
    
    
    /**
     * <p>Returns a copy of the end tangent control that corresponds to
     * the given index 0 or 1.</p>
     *
     * <p>Returns <code>null</code> under the following conditions:</p>
     *
     * <ul>
     *   <li>The given index is not 0 or 1.</li>
     *   <li>The internal vertex array has length N less than 2.</li>
     *   <li>The internal end tangent array is <code>null</code>.</li>
     * </ul>
     *
     * <p>The non-<code>null</code> return value for index = 0 is
     * the first ahead control:</p>
     *
     * <pre>  getVertex(0)   + getEndTangent(0)</pre>
     *
     * <p>The non-<code>null</code> return value for index = 1 is
     * the final behind control:</p>
     *
     * <pre>  getVertex(N-1) - getEndTangent(1)</pre>
     *
     * @param index the end tangent index 0 or 1
     */
    public final float[] getEndTangentControl(int index) {
        if ((index < 0) || (index > 1))
            return null;
        
        int N = vertex.length;
        
        if (N < 2)
            return null;
        
        if (endTangent == null)
            return null;
        
        if (index == 0)
            return new float[]
                { vertex[0][0] + endTangent[0][0],
                  vertex[0][1] + endTangent[0][1] };
        else
            return new float[]
                { vertex[N-1][0] - endTangent[1][0],
                  vertex[N-1][1] - endTangent[1][1] };
    }
    
    
    /**
     * <p>Returns an array <code>float[2][]</code> that contains the two
     * end tangent control points.</p>
     *
     * <p>Specifically, contains:</p>
     *
     * <pre>  getEndTangentControl(0)</pre>
     *
     * <pre>  getEndTangentControl(1)</pre>
     *
     * <p>Note that these control point might be <code>null</code> if the
     * requirements of <code>getEndTangentControl</code> are not met.</p>
     */
    public final float[][] getEndTangentControlData() {
        return new float[][]
            { getEndTangentControl(0),
              getEndTangentControl(1) };
    }
    
    
    /**
     * <p>Returns the index of the first end tangent control
     * that is within epsilon of (x,y)
     * relative to the metric <code>Metric.MAX</code>;
     * returns -1 if no such end tangent control exists.</p>
     *
     * <p>The intended use of this method is to locate
     * an end tangent control
     * using an approximate mouse position.</p>
     *
     * <p>Automatically returns <code>-1</code> if:</p>
     *
     * <ul>
     *   <li>The internal vertex array has length N less than 2.</li>
     *   <li>The internal end tangent array is <code>null</code>.</li>
     * </ul>
     *
     * @param x       the x-coordinate of the search point
     * @param y       the y-coordinate of the search point
     * @param epsilon the measure of closeness
     */
    public final int findEndTangentControl(double x, double y, double epsilon) {
        return findEndTangentControl(x, y, epsilon, Metric.MAX);
    }
    
    
    /**
     * <p>Returns the index of the first end tangent control
     * that is within epsilon of (x,y)
     * relative to the given metric;
     * returns -1 if no such end tangent control exists.</p>
     *
     * <p>If the given metric is <code>null</code>
     * then <code>Metric.MAX</code> is used.</p>
     *
     * <p>The intended use of this method is to locate
     * an end tangent control
     * using an approximate mouse position.</p>
     *
     * <p>Automatically returns <code>-1</code> if:</p>
     *
     * <ul>
     *   <li>The internal vertex array has length N less than 2.</li>
     *   <li>The internal end tangent array is <code>null</code>.</li>
     * </ul>
     *
     * @param x       the x-coordinate of the search point
     * @param y       the y-coordinate of the search point
     * @param epsilon the measure of closeness
     * @param metric  the metric to do the distance computation
     */
    public final int findEndTangentControl
        (double x, double y, double epsilon, Metric metric)
    {
        int N = vertex.length;
        
        if (N < 2)
            return -1;
        
        if (endTangent == null)
            return -1;
        
        if (metric == null)
            metric = Metric.MAX;
        
        float[][] p = getEndTangentControlData();
        
        if (metric.isNear(x, y, p[0][0], p[0][1], epsilon))
            return 0;
        
        if (metric.isNear(x, y, p[1][0], p[1][1], epsilon))
            return 1;
        
        return -1;
    }
    
    
    /**
     * <p>Returns a new <code>PolygonDotsShape</code>
     * whose vertex data is a copy of the end tangent control points.</p>
     *
     * <p>If the necessary conditions for computing control points do
     * not hold then the shape returned will have no dots.
     */
    public final PolygonDotsShape makeEndTangentControlDots() {
        return new PolygonDotsShape(getEndTangentControlData());
    }
    
    
    /**
     * <p>Sets the tangent strategy of the shape and makes a new path.</p>
     *
     * <p>Does nothing if its parameter is <code>null</code>.</p>
     *
     * <p>Fires property change: SET_TANGENT_STRATEGY.</p>
     *
     * @param tangentstrategy the tangent strategy
     */
    public final void setTangentStrategy(Tangent.Strategy tangentstrategy) {
        if ((tangentstrategy == null) || (tangentstrategy == this.tangentstrategy))
            return;
        
        this.tangentstrategy = tangentstrategy;
        
        makePath();
        
        firePropertyChange(SET_TANGENT_STRATEGY, null, null);
    }
    
    
    /**
     * Returns the tangent strategy.
     *
     * @return the tangent strategy
     */
    public final Tangent.Strategy getTangentStrategy() {
        return tangentstrategy;
    }
    
    
    /**
     * Makes the path for this AutomaticShape taking into account
     * the vertex and end tangent arrays and the closure mode to
     * construct the full tangent array automatically using the
     * current tangent strategy as the tangent algorithm.
     */
    protected final void makePath() {
        tangent = (getClosureMode() == ClosureMode.CLOSED)
            ? tangentstrategy.makeTangents(vertex)
            : tangentstrategy.makeTangents(vertex, endTangent);
        
        super.makePath();
    }
    
}