Application: gvSIG desktop

/**

 * gvSIG. Desktop Geographic Information System.

 *

 * Copyright (C) 2007-2013 gvSIG Association.

 *

 * This program is free software; you can redistribute it and/or

 * modify it under the terms of the GNU General Public License

 * as published by the Free Software Foundation; either version 3

 * of the License, or (at your option) any later version.

 *

 * This program is distributed in the hope that it will be useful,

 * but WITHOUT ANY WARRANTY; without even the implied warranty of

 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the

 * GNU General Public License for more details.

 *

 * You should have received a copy of the GNU General Public License

 * along with this program; if not, write to the Free Software

 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston,

 * MA  02110-1301, USA.

 *

 * For any additional information, do not hesitate to contact us

 * at info AT gvsig.com, or visit our website www.gvsig.com.

 */

package org.gvsig.fmap.mapcontext;

import java.awt.Color;

import java.awt.Dimension;

import java.awt.Toolkit;

import java.awt.geom.AffineTransform;

import java.awt.geom.NoninvertibleTransformException;

import java.awt.geom.Point2D;

import java.awt.geom.Rectangle2D;

import java.lang.ref.WeakReference;

import java.util.ArrayList;

import java.util.Collection;

import java.util.Collections;

import java.util.ConcurrentModificationException;

import java.util.List;

import java.util.Objects;

import org.cresques.cts.GeoCalc;

import org.cresques.cts.IProjection;

import org.gvsig.compat.CompatLocator;

import org.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.gvsig.fmap.geom.Geometry.SUBTYPES;

import org.gvsig.fmap.geom.Geometry;

import org.gvsig.fmap.geom.GeometryLocator;

import org.gvsig.fmap.geom.GeometryManager;

import org.gvsig.fmap.geom.exception.CreateEnvelopeException;

import org.gvsig.fmap.geom.exception.CreateGeometryException;

import org.gvsig.fmap.geom.primitive.Envelope;

import org.gvsig.fmap.geom.primitive.Point;

import org.gvsig.fmap.mapcontext.events.ColorEvent;

import org.gvsig.fmap.mapcontext.events.ExtentEvent;

import org.gvsig.fmap.mapcontext.events.ProjectionEvent;

import org.gvsig.fmap.mapcontext.events.listeners.ViewPortListener;

import org.gvsig.timesupport.Time;

import org.gvsig.tools.ToolsLocator;

import org.gvsig.tools.dynobject.DynStruct;

import org.gvsig.tools.lang.Cloneable;

import org.gvsig.tools.persistence.PersistenceManager;

import org.gvsig.tools.persistence.Persistent;

import org.gvsig.tools.persistence.PersistentState;

import org.gvsig.tools.persistence.exception.PersistenceException;

import org.gvsig.tools.util.Callable;

/**

 * <p>

 * <code>ViewPort</code> class represents the logic needed to transform a

 * rectangular area of a map to the available area in screen to display it.

 * </p>

 * <p>

 * Includes an affine transformation, between the rectangular area selected of

 * the external map, in its own <i>map coordinates</i>, to the rectangular area

 * available of a view in <i>screen coordinates</i>.

 * </p>

 * <p>

 * Elements:

 * <ul>

 * <li><i>extent</i>: the area selected of the map, in <i>map coordinates</i>.

 * <li><i>imageSize</i>: width and height in pixels (<i>screen coordinates</i>)

 * of the area available in screen to display the area selected of the map.

 * <li><i>adjustedExtent</i>: the area selected must be an scale of

 * <i>imageSize</i>.<br>

 * This implies adapt the extent, preserving and centering it, and adding around

 * the needed area to fill all the image size. That added area will be extracted

 * from the original map, wherever exists, and filled with the background color

 * wherever not.

 * <li><i>scale</i>: the scale between the adjusted extent and the image size.

 * <li><i>backColor</i>: the default background color in the view, if there is

 * no map.

 * <li><i>trans</i>: the affine transformation.

 * <li><i>proj</i>: map projection used in this view.

 * <li><i>distanceUnits</i>: distance measurement units, of data in screen.

 * <li><i>mapUnits</i>: measurement units, of data in map.

 * <li><i>extents</i>: an {@link ExtentHistory ExtentHistory} with the last

 * previous extents.

 * <li><i>offset</i>: position in pixels of the available rectangular area,

 * where start drawing the map.

 * <li><i>dist1pixel</i>: the distance in <i>world coordinates</i> equivalent to

 * 1 pixel in the view with the current extent.

 * <li><i>dist3pixel</i>: the distance in <i>world coordinates</i> equivalent to

 * 3 pixels in the view with the current extent.

 * <li><i>listeners</i>: list with the {@link ViewPortListener ViewPortListener}

 * registered.

 * </ul>

 * </p>

 *

 * @author Vicente Caballero Navarro

 */

public class ViewPort implements Persistent, Cloneable {

  private static final String FIELD_DISTANCE_AREA = "distanceArea";

  private static final String FIELD_IMAGE_SIZE = "imageSize";

  private static final String FIELD_PROJ = "proj";

  private static final String FIELD_OFFSET = "offset";

  private static final String FIELD_MAP_UNITS = "mapUnits";

  private static final String FIELD_EXTENT = "extent";

  private static final String FIELD_EXTENTS = "extents";

  private static final String FIELD_DISTANCE_UNITS = "distanceUnits";

  private static final String FIELD_DIST3PIXEL = "dist3pixel";

  private static final String FIELD_DIST1PIXEL = "dist1pixel";

  private static final String FIELD_CLIP = "clip";

  private static final String FIELD_BACK_COLOR = "backColor";

  private static final String FIELD_ADJUSTED_EXTENT = "adjustedExtent";

  private static final GeometryManager geomManager = GeometryLocator

      .getGeometryManager();

  private static final Logger logger = LoggerFactory.getLogger(ViewPort.class);

  /**

   * <p>

   * Area selected by user using some tool.

   * </p>

   * <p>

   * When the zoom changes (for instance when using the zoom in or zoom out

   * tools, but also zooming to a selected feature or shape) the extent that

   * covers that area is the value returned by this method. It is not the actual

   * area shown in the view because it does not care about the aspect ratio of

   * the available area. However, any part of the real world contained in this

   * extent is shown in the view.

   * </p>

   * <p>

   * Probably this is not what you are looking for. If you are looking for the

   * complete extent currently shown, you must use

   * {@linkplain #getAdjustedExtent()} method which returns the extent that

   * contains this one but regarding the current view's aspect ratio.

   * </p>

   *

   * @see #getExtent()

   * @see #setEnvelope(Envelope)

   */

  protected Rectangle2D extent;

  protected Time time;

  /**

   * <p>

   * Location and dimensions of the extent adjusted to the image size.

   * </p>

   *

   * @see #getAdjustedExtent()

   */

  protected Rectangle2D adjustedExtent;

  /**

   * Draw version of the context. It's used for know when de componend has

   * changed any visualization property

   *

   * @see getDrawVersion

   * @see updateDrawVersion

   */

  private long drawVersion = 0L;

  /**

   * <p>

   * History with the last extents of the view.

   * </p>

   *

   * @see #setPreviousExtent()

   * @see #getExtents()

   */

  protected ExtentHistory extentsHistory = new ExtentHistory();

  /**

   * <p>

   * Size in <i>screen coordinates</i> of the rectangle where the image is

   * displayed.

   * </p>

   * <p>

   * Used by {@linkplain #calculateAffineTransform()} to calculate:<br>

   * <ul>

   * <li>The new {@link #scale scale} .

   * <li>The new {@link #adjustedExtent adjustableExtent} .

   * <li>The new {@link #trans trans} .

   * <li>The new real world coordinates equivalent to 1 pixel (

   * {@link #dist1pixel dist1pixel}) .

   * <li>The new real world coordinates equivalent to 3 pixels (

   * {@link #dist3pixel dist3pixel}) .

   * </ul>

   * </p>

   *

   * @see #getImageSize()

   * @see #getImageHeight()

   * @see #getImageWidth()

   * @see #setImageSize(Dimension)

   */

  private Dimension imageSize;

  /**

   * <p>

   * the affine transformation between the {@link #extent extent} in <i>map 2D

   * coordinates</i> to the image area in the screen, in <i>screen 2D

   * coordinates</i> (pixels).

   * </p>

   *

   * @see AffineTransform

   * @see #getAffineTransform()

   * @see #setAffineTransform(AffineTransform)

   * @see #calculateAffineTransform()

   */

  private AffineTransform trans = new AffineTransform();

  /**

   * <p>

   * Measurement unit used for measuring distances and displaying information.

   * </p>

   *

   * @see #getDistanceUnits()

   * @see #setDistanceUnits(int)

   */

  private int distanceUnits = 1;

  /**

   * <p>

   * Measurement unit used for measuring areas and displaying information.

   * </p>

   *

   * @see #getDistanceArea()

   * @see #setDistanceArea(int)

   */

  private int distanceArea = 1;

  /**

   * <p>

   * Measurement unit used by this view port for the map.

   * </p>

   *

   * @see #getMapUnits()

   * @see #setMapUnits(int)

   */

  private int mapUnits = 1;

  /**

   * <p>

   * Array with the {@link ViewPortListener ViewPortListener}s registered to

   * this view port.

   * </p>

   *

   * @see #addViewPortListener(ViewPortListener)

   * @see #removeViewPortListener(ViewPortListener)

   */

  private List<ViewPortListener> listeners = new ArrayList<>();

  /**

   * <p>

   * The offset is the position where start drawing the map.

   * </p>

   * <p>

   * The offset of a <a href="http://www.gvsig.gva.es/">gvSIG</a>'s <i>View</i>

   * is always (0, 0) because the drawing area fits with the full window area.

   * But in a <a href="http://www.gvsig.gva.es/">gvSIG</a>'s <i>Layout</i> it's

   * up to the place where the <code>FFrameView</code> is located.

   * </p>

   *

   * @see #getOffset()

   * @see #setOffset(Point2D)

   */

  private Point2D offset = new Point2D.Double(0, 0);

  /**

   * <p>

   * Clipping area.

   * </p>

   */

  // private Rectangle2D clip;

  /**

   * <p>

   * Background color of this view.

   * </p>

   *

   * @see #getBackColor()

   * @see #setBackColor(Color)

   */

  private Color backColor = null; // Color.WHITE;

  /**

   * <p>

   * Information about the map projection used in this view.

   * </p>

   *

   * @see #getProjection()

   * @see #setProjection(IProjection)

   */

  private IProjection proj;

  /**

   * <p>

   * Represents the distance in <i>world coordinates</i> equivalent to 1 pixel

   * in the view with the current extent.

   * </p>

   *

   * @see #getDist1pixel()

   * @see #setDist1pixel(double)

   */

  private double dist1pixel;

  /**

   * <p>

   * Represents the distance in <i>world coordinates</i> equivalent to 3 pixels

   * in the view with the current extent.

   * </p>

   *

   * @see #getDist3pixel()

   * @see #setDist3pixel(double)

   */

  private double dist3pixel;

  /**

   * <p>

   * Ratio between the size of <code>imageSize</code> and <code>extent</code>: <br>

   * <i>

   *

   * <pre>

   * min{(imageSize.getHeight()/extent.getHeight(), imageSize.getWidth()/extent.getWidth())}

   * </pre>

   *

   * </i>

   * </p>

   */

  private double scale;

  /**

   * <p>

   * Clipping area.

   * </p>

   *

   * @see #setClipRect(Rectangle2D)

   */

  private Rectangle2D cliprect;

  /**

   * <p>

   * Enables or disables the <i>"adjustable extent"</i> mode.

   * </p>

   * <p>

   * When calculates the affine transform, if

   * <ul>

   * <li><i>enabled</i>: the new <code>adjustedExtent</code> will have the (X,

   * Y) coordinates of the <code>extent</code> and an area that will be an scale

   * of the image size. That area will have different height or width (not both)

   * of the extent according the least ratio (height or width) in

   *

   * <pre>

   * image.size/extent.size"

   * </pre>.

   * <li><i>disabled</i>: the new <code>adjustedExtent</code> will be like

   * <code>extent</code>.

   * </ul>

   * </p>

   *

   * @see #setAdjustable(boolean)

   */

  private boolean adjustableExtent = true;

  /**

   * <p>

   * ViewPort resolution in <i>dots-per-inch</i>. Useful to calculate the

   * geographic scale of the view.

   * </p>

   *

   * @see Toolkit#getScreenResolution()

   * @see MapContext#getScaleView()

   */

  private Double dpi = null;

  public ViewPort() {

  }

  /**

   * <p>

   * Creates a new view port with the information of the projection in

   * <code>proj</code> argument, and default configuration:

   * </p>

   * <p>

   * <ul>

   * <li><i><code>distanceUnits</code></i> = meters

   * <li><i><code>mapUnits</code></i> = meters

   * <li><i><code>backColor</code></i> = <i>undefined</i>

   * <li><i><code>offset</code></i> = <code>new Point2D.Double(0, 0);</code>

   * </ul>

   * </p>

   *

   * @param proj information of the projection for this view port

   */

  public ViewPort(IProjection proj) {

    // Por defecto

    this.proj = proj;

  }

  /**

   * <p>

   * Changes the status of the <i>"adjustable extent"</i> option to enabled or

   * disabled.

   * </p>

   * <p>

   * If view port isn't adjustable, won't bear in mind the aspect ratio of the

   * available rectangular area to calculate the affine transform from the

   * original map in real coordinates. (Won't scale the image to adapt it to the

   * available rectangular area).

   * </p>

   *

   * @param boolean the boolean to be set

   */

  public void setAdjustable(boolean adjustable) {

    if (adjustable == adjustableExtent) {

      return;

    }

    adjustableExtent = adjustable;

    this.updateDrawVersion();

  }

    private Collection<ViewPortListener> getListeners() {

        List<ViewPortListener> ll = Collections.unmodifiableList(listeners);

        return ll;

    }

  /**

   * <p>

   * Appends the specified {@link ViewPortListener ViewPortListener} listener if

   * weren't.

   * </p>

   *

   * @param listener the listener to add

   * @return <code>true</code> if has been added successfully

   * @see #removeViewPortListener(ViewPortListener)

   */

    public boolean addViewPortListener(ViewPortListener listener) {

        if (listener == null) {

            return false;

        }

        if( this.listeners.contains(listener) )  {

            return false;

        }

        this.listeners.add(listener);

        return true;

    }

  /**

   * <p>

   * Removes the specified {@link ViewPortListener ViewPortListener} listener,

   * if existed.

   * </p>

   *

   * @param listener the listener to remove

   * @return <code>true</code> if the contained the specified listener.

   * @see #addViewPortListener(ViewPortListener)

   */

    public boolean removeViewPortListener(ViewPortListener listener) {

        if (listener == null) {

            return false;

        }

        return this.listeners.remove(listener);

    }

  /**

   * <p>

   * Converts and returns the distance <code>d</code>, that is in <i>map

   * coordinates</i> to <i>screen coordinates</i> using a <i>delta transform</i>

   * with the transformation affine information in the {@link #trans #trans}

   * attribute.

   * </p>

   *

   * @param d distance in <i>map coordinates</i>

   * @return distance equivalent in <i>screen coordinates</i>

   * @see #toMapDistance(int)

   * @see AffineTransform#deltaTransform(Point2D, Point2D)S

   */

  public int fromMapDistance(double d) {

    Point2D.Double pWorld = new Point2D.Double(1, 1);

    Point2D.Double pScreen = new Point2D.Double();

    try {

      trans.deltaTransform(pWorld, pScreen);

    }

    catch (Exception e) {

      System.err.print(e.getMessage());

    }

    return (int) (d * pScreen.x);

  }

  /**

   * <p>

   * Converts and returns the 2D point <code>(x,y)</code>, that is in <i>map

   * coordinates</i> to <i>screen coordinates</i> (pixels) using the affine

   * transformation in the {@link #trans #trans} attribute.

   * </p>

   *

   * @param x the <code>x</code> <i>map coordinate</i> of a 2D point

   * @param y the <code>y</code> <i>map coordinate</i> of a 2D point

   * @return 2D point equivalent in <i>screen coordinates</i> (pixels)

   * @see #fromMapPoint(Point2D)

   * @see AffineTransform#transform(Point2D, Point2D)

   */

  public Point2D fromMapPoint(double x, double y) {

    Point2D.Double pWorld = new Point2D.Double(x, y);

    Point2D.Double pScreen = new Point2D.Double();

    try {

      trans.transform(pWorld, pScreen);

    }

    catch (Exception e) {

      System.err.print(e.getMessage());

    }

    return pScreen;

  }

  /**

   * <p>

   * Converts and returns the 2D point argument, that is in <i>map

   * coordinates</i> to <i>screen coordinates</i> (pixels) using the affine

   * transformation in the {@link #trans #trans} attribute.

   * </p>

   *

   * @param point the 2D point in <i>map coordinates</i>

   * @return 2D point equivalent in <i>screen coordinates</i> (pixels)

   * @see #toMapPoint(Point2D)

   * @see #fromMapPoint(double, double)

   */

  public Point2D fromMapPoint(Point2D point) {

    return fromMapPoint(point.getX(), point.getY());

  }

  /**

   * <p>

   * Converts and returns the 2D point <code>(x,y)</code>, that is in <i>screen

   * coordinates</i> (pixels) to <i>map coordinates</i> using the affine

   * transformation in the {@link #trans #trans} attribute.

   * </p>

   *

   * @param x the <code>x</code> <i>screen coordinate</i> of a 2D point

   * @param y the <code>y</code> <i>screen coordinate</i> of a 2D point

   * @return 2D point equivalent in <i>map coordinates</i>

   * @see #toMapPoint(Point2D)

   * @see #fromMapPoint(double, double)

   * @deprecated use {@link #convertToMapPoint(int, int)}

   */

  public Point2D toMapPoint(int x, int y) {

    Point2D pScreen = new Point2D.Double(x, y);

    return toMapPoint(pScreen);

  }

  /**

   * <p>

   * Converts and returns the {@link Rectangle2D Rectangle2D}, that is in

   * <i>screen coordinates</i> (pixels) to <i>map coordinates</i> using

   * {@linkplain #toMapDistance(int)}, and {@linkplain #toMapPoint(int, int)}.

   * </p>

   *

   * @param r the 2D rectangle in <i>screen coordinates</i> (pixels)

   * @return 2D rectangle equivalent in <i>map coordinates</i>

   * @see #fromMapRectangle(Rectangle2D)

   * @see #toMapDistance(int)

   * @see #toMapPoint(int, int)

   */

  public Rectangle2D toMapRectangle(Rectangle2D r) {

    Rectangle2D rect = new Rectangle2D.Double();

    Point2D p1 = toMapPoint((int) r.getX(), (int) r.getY());

    Point2D p2 = toMapPoint((int) r.getMaxX(), (int) r.getMaxY());

    rect.setFrameFromDiagonal(p1, p2);

    return rect;

  }

  /**

   * <p>

   * Converts and returns the distance <code>d</code>, that is in <i>screen

   * coordinates</i> to <i>map coordinates</i> using the transformation affine

   * information in the {@link #trans #trans} attribute.

   * </p>

   *

   * @param d distance in pixels

   * @return distance equivalent in <i>map coordinates</i>

   * @see #fromMapDistance(double)

   * @see AffineTransform

   */

  public double toMapDistance(int d) {

    double dist = d / trans.getScaleX();

    return dist;

  }

  /**

   * <p>

   * Converts and returns the 2D point argument, that is in <i>screen

   * coordinates</i> (pixels) to <i>map coordinates</i> using the inverse affine

   * transformation of the {@link #trans #trans} attribute.

   * </p>

   *

   * @param pScreen the 2D point in <i>screen coordinates</i> (pixels)

   * @return 2D point equivalent in <i>map coordinates</i>

   * @see #toMapPoint(int, int)

   * @see AffineTransform#createInverse()

   * @see AffineTransform#transform(Point2D, Point2D)

   * @deprecated use {@link #convertToMapPoint(Point2D)}

   */

  public Point2D toMapPoint(Point2D pScreen) {

    Point2D.Double pWorld = new Point2D.Double();

    AffineTransform at;

    if( pScreen == null ) {

        return null;

    }

    try {

      at = trans.createInverse();

      at.transform(pScreen, pWorld);

    }

    catch (NoninvertibleTransformException e) {

      throw new RuntimeException("Non invertible transform Exception", e);

    }

    return pWorld;

  }

  public Point convertToMapPoint(Point2D pScreen) {

    Point2D p = toMapPoint(pScreen);

    try {

        Point point = geomManager.createPoint(

                p.getX(), 

                p.getY(),

                Geometry.SUBTYPES.GEOM2D

        );

        point.setProjection(this.getProjection());

        return point;

    }

    catch (CreateGeometryException e) {

      // FIXME: Use a most especific exception.

      throw new RuntimeException(e);

    }

  }

  public Point convertToMapPoint(int x, int y) {

    Point2D pScreen = new Point2D.Double(x, y);

    return convertToMapPoint(pScreen);

  }

  /**

   * <p>

   * Returns the real distance (in <i>world coordinates</i>) at the graphic

   * layers of two 2D points (in <i>map coordinates</i>) of the plane where is

   * selected the <i>extent</i>.

   * </p>

   * <p>

   * If the projection of this view is UTM, considers the Earth curvature.

   * </p>

   *

   * @param pt1 a 2D point in <i>map coordinates</i>

   * @param pt2 another 2D point in <i>map coordinates</i>

   * @return the distance in meters between the two points 2D

   * @see GeoCalcImpl#distanceVincenty(Point2D, Point2D)

   */

  public double distanceWorld(Point2D pt1, Point2D pt2) {

    double dist = 0;

    if (proj.isProjected()) {

      dist = pt1.distance(pt2);

      dist = dist * MapContext.getDistanceTrans2Meter()[getMapUnits()];

    }

    else {

      GeoCalc geocalc = new GeoCalc(proj);

      dist = geocalc.distanceVincenty(pt1, pt2);

    }

    return dist;

  }

  /**

   * <p>

   * Sets as extent and adjusted extent of this view port, the previous.

   * Recalculating its parameters.

   * </p>

   *

   * @see #getExtents()

   * @see #calculateAffineTransform()

   * @deprecated use {@link ViewPort#setPreviousEnvelope()}

   */

  public void setPreviousExtent() {

    setPreviousEnvelope();

  }

  /**

   * <p>

   * Sets as envelope and adjusted envelope of this view port, the previous.

   * Recalculating its parameters.

   * Stores the current extent in the next extents of the history.

   * </p>

   *

   * @see #getExtents()

   * @see #calculateAffineTransform()

   */

  public void setPreviousEnvelope() {

    this.updateDrawVersion();

//    extentsHistory.putNext(extent);

//    extent = extentsHistory.removePrev();

    extent = extentsHistory.setPreviousExtent();

    // Calcula la transformaci?n af?n

    calculateAffineTransform();

    // Lanzamos los eventos de extent cambiado

    callExtentChanged(getAdjustedExtent());

  }

  /**

   * <p>

   * Sets as envelope and adjusted envelope of this view port, the next.

   * Recalculating its parameters.

   * Stores the current extent in the previous extents of the history.

   * </p>

   *

   * @see #getExtents()

   * @see #calculateAffineTransform()

   */

  public void setNextEnvelope() {

    this.updateDrawVersion();

    extent = extentsHistory.setNextExtent();

    // Calcula la transformaci?n af?n

    calculateAffineTransform();

    // Lanzamos los eventos de extent cambiado

    callExtentChanged(getAdjustedExtent());

  }

  /**

   * <p>

   * Gets the area selected by user using some tool.

   * </p>

   * <p>

   * When the zoom changes (for instance using the <i>zoom in</i> or <i>zoom

   * out</i> tools, but also zooming to a selected feature or shape) the extent

   * that covers that area is the value returned by this method. It is not the

   * actual area shown because it doesn't care about the aspect ratio of the

   * image size of the view. However, any part of the real world contained in

   * this extent is shown in the view.

   * </p>

   * <p>

   * If you are looking for the complete extent currently shown, you must use

   * the {@linkplain #getAdjustedExtent()} method.

   * </p>

   *

   * @return the current extent

   * @see #setEnvelope(Envelope)

   * @see #getAdjustedExtent()

   * @see #setPreviousExtent()

   * @see #getExtents()

   * @deprecated use {@link ViewPort#getEnvelope()}

   */

  public Rectangle2D getExtent() {

    return extent;

  }

  /**

   * <p>

   * Gets the envelope selected by user using some tool.

   * </p>

   * <p>

   * When the zoom changes (for instance using the <i>zoom in</i> or <i>zoom

   * out</i> tools, but also zooming to a selected feature or shape) the

   * envelope that covers that area is the value returned by this method. It is

   * not the actual envelope shown because it doesn't care about the aspect

   * ratio of the image size of the view. However, any part of the real world

   * contained in this envelope is shown in the view.

   * </p>

   * <p>

   * If you are looking for the complete extent currently shown, you must use

   * the {@linkplain #getAdjustedEnvelope()} method.

   * </p>

   *

   * @return the current envelope

   * @see #setEnvelope(Envelope)

   * @see #getAdjustedEnvelope()

   * @see #setPreviousEnvelope()

   * @see #getEnvelopes()

   */

  public Envelope getEnvelope() {

    if (this.extent == null) {

      return null;

    }

    try {

        Envelope envelope = geomManager.createEnvelope(

                extent.getMinX(), 

                extent.getMinY(),

                extent.getMaxX(), 

                extent.getMaxY(), 

                SUBTYPES.GEOM2D

        );

        envelope.setProjection(this.proj);

        return envelope;

        // This class has to use Envelope instead of Rectangle2D. This catch

        // will disappear

    } catch (CreateEnvelopeException e) {

      logger.warn("Error creating the ViewPort envelope.", e);

    }

    return null;

  }

  /**

   * <p>

   * Changes the <i>extent</i> and <i>adjusted extent</i> of this view port:<br>

   * <ul>

   * <li>Stores the previous extent.

   * <li>Calculates the new extent using <code>r</code>:

   *

   * <pre>

   * extent = new Rectangle2D.Double(r.getMinX() - 0.1, r.getMinY() - 0.1,

   *     r.getWidth() + 0.2, r.getHeight() + 0.2);

   * </pre>

   * <li>Executes {@linkplain #calculateAffineTransform()}: getting the new

   * scale, adjusted extent, affine transformation between map and screen

   * coordinates, the real world coordinates equivalent to 1 pixel, and the real

   * world coordinates equivalent to 3 pixels.

   * <li>Notifies all {@link ViewPortListener ViewPortListener} registered that

   * the extent has changed.

   * </ul>

   * </p>

   *

   * @param r the new extent

   * @see #getExtent()

   * @see #getExtents()

   * @see #calculateAffineTransform()

   * @see #setPreviousExtent()

   * @see #clear()

   */

  public void setEnvelope(Envelope r) {

    Rectangle2D newExtent = null;

    // Esto comprueba que el extent no es de anchura o altura = "0"

    // y si es as? lo redimensiona.

    if (r != null) { 

      if ((r.getMaximum(0) - r.getMinimum(0) == 0)

          || (r.getMaximum(1) - r.getMinimum(1) == 0)) {

        newExtent = new Rectangle2D.Double(r.getMinimum(0) - 0.1,

            r.getMinimum(1) - 0.1, r.getMaximum(0) - r.getMinimum(0) + 0.2,

            r.getMaximum(1) - r.getMinimum(1) + 0.2);

      }

      else {

        newExtent = new Rectangle2D.Double(r.getMinimum(0), r.getMinimum(1),

            Math.abs(r.getMaximum(0) - r.getMinimum(0)), Math.abs(r

                .getMaximum(1) - r.getMinimum(1)));

      }

    }

    if (this.extent != null && this.extent.equals(newExtent)) {

      return;

    }

    this.updateDrawVersion();

    this.extent = newExtent;

    try {

        calculateAffineTransform();

    } catch(Exception ex) {

        this.extent = null;

        throw ex;

    }

    extentsHistory.put(extent);

    // Lanzamos los eventos de extent cambiado

    callExtentChanged(getAdjustedExtent());

  }

  /**

   * <p>

   * Changes the <i>extent</i> and <i>adjusted extent</i> of this view port:<br>

   * <ul>

   * <li>Executes {@linkplain #calculateAffineTransform()}: getting the new

   * scale, adjusted extent, affine transformation between map and screen

   * coordinates, the real world coordinates equivalent to 1 pixel, and the real

   * world coordinates equivalent to 3 pixels.

   * <li>Notifies to all {@link ViewPortListener ViewPortListener} registered

   * that the extent has changed.

   * </ul>

   * </p>

   *

   * @see #setEnvelope(Envelope)

   * @see #calculateAffineTransform()

   */

  public void refreshExtent() {

    //Por compatibilidad con versiones anteriores a la introducci?n de las lista de zooms siguientes

    if (extentsHistory.getCurrent() == null) {

      extentsHistory.put(extent);

    } else {

      extent = extentsHistory.getCurrent();

    }

    // Calcula la transformaci?n af?n

    calculateAffineTransform();

    // Lanzamos los eventos de extent cambiado

    callExtentChanged(getAdjustedExtent());

  }

  /**

   * <p>

   * Calculates and returns using the current projection of this view port, the

   * scale that is the extent in <i>screen coordinates</i> from the image in

   * <i>map coordinates</i>.

   * </p>

   *

   * @return the scale <i>extent / image size</i> projected by this view port

   * @deprecated since 07/09/07, use {@linkplain MapContext#getScaleView()}

   */

  private double getScale() {

    double[] trans2Meter = MapContext.getDistanceTrans2Meter();

    if (proj == null) {

      double wmeters = ((getImageSize().width / this.getDPI()) * 0.0254);

      return (long) ((trans2Meter[getMapUnits()] * getAdjustedEnvelope()

          .getLength(0)) / wmeters);

    }

    else {

      return Math.round(proj.getScale(getAdjustedEnvelope().getMinimum(0)

          * trans2Meter[getMapUnits()], getAdjustedEnvelope().getMaximum(0)

          * trans2Meter[getMapUnits()], getImageSize().width, this.getDPI()));

    }

    /*

     * return proj.getScale(extent.getMinX(), extent.getMaxX(), imageSize.width,

     * dpi);

     */

  }

  /**

   * <p>

   * Affine transformation between <i>map 2D coordinates</i> to <i>screen 2D

   * coordinates</i> (pixels), preserving the "straightness" and "parallelism"

   * of the lines.

   * </p>

   *

   * @return the affine transformation

   * @see #setAffineTransform(AffineTransform)

   * @see #calculateAffineTransform()

   */

  public AffineTransform getAffineTransform() {

    return trans;

  }

  /**

   * <p>

   * Returns the size of the image projected.

   * </p>

   *

   * @return the image size

   * @see #setImageSize(Dimension)

   * @see #getImageHeight()

   * @see #getImageWidth()

   */

  public Dimension getImageSize() {

    return imageSize;

  }

  /**

   * <p>

   * Sets the size of the image projected, recalculating the parameters of this

   * view port.

   * </p>

   *

   * @param imageSize the image size

   * @see #getImageSize()

   * @see #calculateAffineTransform()

   */

  public void setImageSize(Dimension imageSize) {

    if (this.imageSize == null || (!this.imageSize.equals(imageSize))) {

      this.updateDrawVersion();

      this.imageSize = imageSize;

      calculateAffineTransform();

    }

  }

  /**

   * <p>

   * Notifies to all view port listeners registered, that the adjusted extent of

   * this view port has changed.

   * </p>

   *

   * @param newRect the new adjusted extend

   * @see #refreshExtent()

   * @see #setEnvelope(Envelope)

   * @see #setPreviousExtent()

   * @see ExtentEvent

   * @see ViewPortListener

   */

    protected void callExtentChanged(Envelope newRect) {

        ExtentEvent ev = ExtentEvent.createExtentEvent(newRect);

        for (ViewPortListener listener : this.getListeners()) {

            if (listener != null) {

                listener.extentChanged(ev);

            }

        }

    }

  /**

   * <p>

   * Notifies to all view port listeners registered, that the time of this view

   * port has changed.

   * </p>

   *

   * @param newTime the new time

   * @see #refreshExtent()

   * @see #setTime(Time)

   * @see ExtentEvent

   * @see ViewPortListener

   */

    protected void callTimeChanged(Time newTime) {

        ExtentEvent viewPortEvent = new ExtentEvent(newTime);

        for (ViewPortListener listener : this.getListeners()) {

            if (listener != null) {

                listener.extentChanged(viewPortEvent);

            }

        }

    }

  /**

   * <p>

   * Notifies to all view port listeners registered, that the background color

   * of this view port has changed.

   * </p>

   *

   * @param c the new background color

   * @see #setBackColor(Color)

   * @see ColorEvent

   * @see ViewPortListener

   */

    private void callColorChanged(Color c) {

        ColorEvent ce = ColorEvent.createColorEvent(c);

        for (ViewPortListener listener : this.getListeners()) {

            if (listener != null) {

                listener.backColorChanged(ce);

            }

        }

    }

  /**

   * <p>

   * Notifies to all view port listeners registered, that the projection of this

   * view port has changed.

   * </p>

   *

   * @param projection the new projection

   * @see #setProjection(IProjection)

   * @see ProjectionEvent

   * @see ViewPortListener

   */

    private void callProjectionChanged(IProjection projection) {

        ProjectionEvent ev = ProjectionEvent.createProjectionEvent(projection);

        for (ViewPortListener listener : this.getListeners()) {

            if (listener != null) {

                listener.projectionChanged(ev);

            }

        }

    }

  /**

   * <p>

   * Calculates the affine transformation between the {@link #extent extent} in

   * <i>map 2D coordinates</i> to the image area in the screen, in <i>screen 2D

   * coordinates</i> (pixels).

   * </p>

   * <p>

   * This process recalculates some parameters of this view port:<br>

   * <ul>

   * <li>The new {@link #scale scale} .

   * <li>The new {@link #adjustedExtent adjustedExtent} .

   * <li>The new {@link #trans trans} .

   * <li>The new real world coordinates equivalent to 1 pixel (

   * {@link #dist1pixel dist1pixel}) .

   * <li>The new real world coordinates equivalent to 3 pixels (

   * {@link #dist3pixel dist3pixel}) .

   * </ul>

   * </p>

   *

   * @see #getAffineTransform()

   * @see #setAffineTransform(AffineTransform)

   * @see #refreshExtent()

   * @see #setEnvelope(Envelope)

   * @see #setImageSize(Dimension)

   * @see #setPreviousExtent()

   * @see #createFromXML(XMLEntity)

   * @see AffineTransform

   */

  private void calculateAffineTransform() {

    if ((imageSize == null) || (extent == null) || (imageSize.width <= 0)

        || (imageSize.height <= 0)) {

      return;

    }

    AffineTransform escalado = new AffineTransform();

    AffineTransform translacion = new AffineTransform();

    double escalaX;

    double escalaY;

    escalaX = imageSize.width / extent.getWidth();

    escalaY = imageSize.height / extent.getHeight();

    double xCenter = extent.getCenterX();

    double yCenter = extent.getCenterY();

    double newHeight;

    double newWidth;

    adjustedExtent = new Rectangle2D.Double();

    if (adjustableExtent) {

      if (escalaX < escalaY) {

        scale = escalaX;

        newHeight = imageSize.height / scale;

        adjustedExtent.setRect(xCenter - (extent.getWidth() / 2.0), yCenter

            - (newHeight / 2.0), extent.getWidth(), newHeight);

      }

      else {

        scale = escalaY;

        newWidth = imageSize.width / scale;

        adjustedExtent.setRect(xCenter - (newWidth / 2.0),

            yCenter - (extent.getHeight() / 2.0), newWidth, extent.getHeight());

      }

      escalado.setToScale(scale, -scale);

    }

    else { // adjusted is same as extent

      scale = escalaX;

      adjustedExtent.setFrame(extent);

      escalado.setToScale(escalaX, -escalaY);

    }

    Envelope env = getAdjustedExtent();

    if (env == null) {

      return;

    }

    translacion.setToTranslation(-env.getMinimum(0), -env.getMinimum(1)

        - getAdjustedExtent().getLength(1));

    AffineTransform offsetTrans = new AffineTransform();

    offsetTrans.setToTranslation(offset.getX(), offset.getY());

    trans.setToIdentity();

    trans.concatenate(offsetTrans);

    trans.concatenate(escalado);

    trans.concatenate(translacion);

    // Calculamos las distancias de 1 pixel y 3 pixel con esa

    // transformaci?n

    // de coordenadas, de forma que est?n precalculadas para cuando las

    // necesitemos

    AffineTransform at;

    try {

      at = trans.createInverse();

      Point2D pPixel = new Point2D.Float(1, 1);

      Point2D.Float pProv = new Point2D.Float();

      at.deltaTransform(pPixel, pProv);

      dist1pixel = pProv.x;

      dist3pixel = 3 * pProv.x;

    }

    catch (NoninvertibleTransformException e) {

      String msg = "Can't calculate affine transform for the view port." + "\n" +

        "The extent can be out of range for this projection." + "\n" +

        "transformada afin: " + Objects.toString(trans) + "\n" +

        "extent: " + Objects.toString(extent) + "\n" +

        "imageSize: " + Objects.toString(imageSize) + "\n" +

        "projection: " + Objects.toString(proj) + "\n" +

        e.getLocalizedMessage() 

      ;

      logger.error(msg, e);

      trans.setToIdentity();

      scale = 0;

      adjustedExtent = null;

      adjustableExtent = true;

      throw new RuntimeException(msg, e);

    }

  }

  /**

   * <p>

   * Sets the offset.

   * </p>

   * <p>

   * The offset is the position where start drawing the map.

   * </p>

   *

   * @param p 2D point that represents the offset in pixels

   * @see #getOffset()

   */

  public void setOffset(Point2D p) {

    if (!offset.equals(p)) {

      this.updateDrawVersion();

      offset = p;

    }

  }

  /**

   * <p>

   * Gets the offset.

   * </p>

   * <p>

   * The offset is the position where start drawing the map.

   * </p>

   *

   * @return 2D point that represents the offset in pixels

   * @see #setOffset(Point2D)

   */

  public Point2D getOffset() {

    return offset;

  }

  /**

   * <p>

   * Sets the background color.

   * </p>

   *

   * @param c the new background color

   * @see #getBackColor()

   */

  public void setBackColor(Color c) {

    if (!c.equals(this.backColor)) {

      this.updateDrawVersion();

      backColor = c;

      callColorChanged(backColor);

    }

  }

  /**

   * <p>

   * Gets the background color.

   * </p>

   *

   * @return the background color of the view

   * @see #setBackColor(Color)

   */

  public Color getBackColor() {

    return backColor;

  }

  /**

   * <p>

   * Returns the extent currently covered by the view adjusted (scaled) to the

   * image size aspect.

   * </p>

   *

   * @return extent of the view adjusted to the image size aspect

   * @see #setAdjustable(boolean)

   * @deprecated use {@link ViewPort#getAdjustedEnvelope()} instead

   */

  public Envelope getAdjustedExtent() {

    return getAdjustedEnvelope();

  }

  /**

   * <p>

   * Returns the envelope currently covered by the view adjusted (scaled) to the

   * image size aspect.

   * </p>

   *