| gvSIG desktop 1

/* gvSIG. Sistema de Informaci?n Geogr?fica de la Generalitat Valenciana

 *

 * Copyright (C) 2004 IVER T.I. and Generalitat Valenciana.

 *

 * 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 2

 * 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., 59 Temple Place - Suite 330, Boston, MA  02111-1307,USA.

 *

 * For more information, contact:

 *

 *  Generalitat Valenciana

 *   Conselleria d'Infraestructures i Transport

 *   Av. Blasco Ib??ez, 50

 *   46010 VALENCIA

 *   SPAIN

 *

 *      +34 963862235

 *   gvsig@gva.es

 *      www.gvsig.gva.es

 *

 *    or

 *

 *   IVER T.I. S.A

 *   Salamanca 50

 *   46005 Valencia

 *   Spain

 *

 *   +34 963163400

 *   dac@iver.es

 */

package org.gvsig.fmap.mapcontext;

import java.awt.Color;

import java.awt.Dimension;

import java.awt.Toolkit;

import java.awt.color.ColorSpace;

import java.awt.geom.AffineTransform;

import java.awt.geom.NoninvertibleTransformException;

import java.awt.geom.Point2D;

import java.awt.geom.Rectangle2D;

import java.util.ArrayList;

import java.util.Iterator;

import org.cresques.cts.GeoCalc;

import org.cresques.cts.IProjection;

import org.cresques.cts.UTM;

import org.gvsig.compat.CompatLocator;

import org.gvsig.fmap.geom.GeometryLocator;

import org.gvsig.fmap.geom.GeometryManager;

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

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

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

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.tools.ToolsLocator;

import org.gvsig.tools.dynobject.DynStruct;

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.slf4j.Logger;

import org.slf4j.LoggerFactory;

import org.gvsig.tools.lang.Cloneable;

/**

 * <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>

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

     * geographic scale of the view.

     * </p>

     * 

     * @see Toolkit#getScreenResolution()

     * @see #getScale()

     */

    private static int dpi = java.awt.Toolkit.getDefaultToolkit()

        .getScreenResolution();

    /**

     * <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;

    /**

     * <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 extents = 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 ArrayList 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;

    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();

    }

    /**

     * <p>

     * Appends the specified {@link ViewPortListener ViewPortListener} listener

     * if weren't.

     * </p>

     * 

     * @param arg0

     *            the listener to add

     * 

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

     * 

     * @see #removeViewPortListener(ViewPortListener)

     */

    public boolean addViewPortListener(ViewPortListener arg0) {

        if (!listeners.contains(arg0)) {

            return listeners.add(arg0);

        }

        return false;

    }

    /**

     * <p>

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

     * if existed.

     * </p>

     * 

     * @param arg0

     *            the listener to remove

     * 

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

     * 

     * @see #addViewPortListener(ViewPortListener)

     */

    public boolean removeViewPortListener(ViewPortListener arg0) {

        return listeners.remove(arg0);

    }

    /**

     * <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)

     */

    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)

     */

    public Point2D toMapPoint(Point2D pScreen) {

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

        AffineTransform at;

        try {

            at = trans.createInverse();

            at.transform(pScreen, pWorld);

        } catch (NoninvertibleTransformException e) {

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

        }

        return pWorld;

    }

    /**

     * <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 = -1;

        dist = pt1.distance(pt2);

        if ((proj != null) && !(proj instanceof UTM)) {

            dist =

                new GeoCalc(proj).distanceVincenty(proj.toGeo(pt1),

                    proj.toGeo(pt2));

            return dist;

        }

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

    }

    /**

     * <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.

     * </p>

     * 

     * @see #getExtents()

     * @see #calculateAffineTransform()

     */

    public void setPreviousEnvelope() {

        this.updateDrawVersion();

        extent = extents.removePrev();

        // 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 {

            return geomManager.createEnvelope(extent.getMinX(),

                extent.getMinY(),

                extent.getMaxX(),

                extent.getMaxY(),

                SUBTYPES.GEOM2D);

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

            // will disappear

        } catch (CreateEnvelopeException e) {

            logger.error("Error creating the envelope");

        }

        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()

     */

    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;

        }

        if (extent != null) {

            extents.put(extent);

        }

        this.updateDrawVersion();

        this.extent = newExtent;

        // Calcula la transformaci?n af?n

        calculateAffineTransform();

        // 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() {

        // this.scale = scale;

        // 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()}

     */

    public double getScale() {

        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 (int i = 0; i < listeners.size(); i++) {

            ViewPortListener listener = (ViewPortListener) listeners.get(i);

            listener.extentChanged(ev);

        }

    }

    /**

     * <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 (int i = 0; i < listeners.size(); i++) {

            ViewPortListener listener = (ViewPortListener) listeners.get(i);

            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 (int i = 0; i < listeners.size(); i++) {

            ViewPortListener listener = (ViewPortListener) listeners.get(i);

            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) {

            System.err.println("transformada afin = " + trans.toString());

            System.err.println("extent = " + extent.toString() + " imageSize= "

                + imageSize.toString());

            throw new RuntimeException("Non invertible transform Exception", 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>

     * 

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

     * 

     * @see #setAdjustable(boolean)

     */

    public Envelope getAdjustedEnvelope() {

        if (cliprect != null) {

            Rectangle2D r = adjustedExtent.createIntersection(cliprect);

            try {

                return geomManager.createEnvelope(r.getX(),

                    r.getY(),

                    r.getMaxX(),

                    r.getMaxY(),

                    SUBTYPES.GEOM2D);

            } catch (CreateEnvelopeException e) {

                e.printStackTrace();

                logger.error("Error adjusting the extent", e);

            }

        }

        if (adjustedExtent != null) {

            try {

                return geomManager.createEnvelope(adjustedExtent.getX(),

                    adjustedExtent.getY(),

                    adjustedExtent.getMaxX(),

                    adjustedExtent.getMaxY(),

                    SUBTYPES.GEOM2D);

            } catch (CreateEnvelopeException e) {

                e.printStackTrace();

                logger.error("Error adjusting the extent", e);

            }

        }

        return null;

    }

    /**

     * <p>

     * Returns the measurement unit of this view port used for measuring

     * distances and displaying information.

     * </p>

     * 

     * @return the measurement unit of this view used for measuring distances

     *         and displaying information

     * 

     * @see #setDistanceUnits(int)

     */

    public int getDistanceUnits() {

        return distanceUnits;

    }

    /**

     * <p>

     * Returns the measurement unit of this view port used for measuring areas

     * and displaying information.

     * </p>

     * 

     * @return the measurement unit of this view used for measuring areas and

     *         displaying information

     * 

     * @see #setDistanceUnits(int)

     */

    public int getDistanceArea() {

        return distanceArea;

    }

    /**

     * <p>