org.geotools.map

Class MapViewport

Object

MapViewport

public class MapViewport
extends Object

Represents the area of a map to be displayed, expressed in world coordinates and (optionally) screen (window, image) coordinates. A viewport is used to stage information for map rendering. While the viewport provides support for bounds and coordinate reference system out of the box it is expected that the user data support in MapContent will be used to record additional information such as elevation and time as required for rendering.

When both world and screen bounds are defined, the viewport calculates AffineTransforms to convert the coordinates of one bounds to those of the other. It can also optionally adjust the world bounds to maintain an identical aspect ratio with the screen bounds. Note however that aspect ratio adjustment should not be enabled when the viewport is used with a service such as WMS which mandates that specified screen and world bounds must be honoured exactly, regardless of the resulting aspect ratio differences.

The AffineTransforms can be retrieved with the methods getScreenToWorld() and getWorldToScreen(). The following rules apply to the return values of these methods:

• If screen area is not defined, null is returned.
• If screen area only is defined, the identity transform is returned.
• If both screen area and world extent are defined, calculated transforms are returned.

Since:

2.7

Author:

Jody Garnett, Michael Bedward

Field Summary

Fields

Modifier and Type	Field and Description
protected static Logger	LOGGER The logger for the map module.

Constructor Summary

Constructors

Constructor and Description
MapViewport() Creates a new view port.
MapViewport(boolean matchAspectRatio) Creates a new view port.
MapViewport(MapViewport sourceViewport) Creates a new viewport based on an existing instance.
MapViewport(ReferencedEnvelope bounds) Creates a new view port with the specified display area in world coordinates.
MapViewport(ReferencedEnvelope bounds, boolean matchAspectRatio) Creates a new viewport with the specified world bounds.

Method Summary

Modifier and Type	Method and Description
void	addMapBoundsListener(MapBoundsListener listener) Used by client application to track the bounds of this viewport.
protected void	fireMapBoundsListenerMapBoundsChanged(MapBoundsEvent.Type type, ReferencedEnvelope oldBounds, ReferencedEnvelope newBounds) Notifies MapBoundsListeners about a change to the bounds or crs.
ReferencedEnvelope	getBounds() Gets the display area in world coordinates.
CoordinateReferenceSystem	getCoordinateReferenceSystem() The coordinate reference system used for rendering the map.
Rectangle	getScreenArea() Gets a copy of the current screen area.
AffineTransform	getScreenToWorld() Gets the current screen to world coordinate transform.
AffineTransform	getWorldToScreen() Gets the current world to screen coordinate transform.
boolean	isEditable() Tests whether this viewport's attributes can be changed.
boolean	isEmpty() Checks if the view port bounds are empty (undefined).
boolean	isMatchingAspectRatio() Queries whether input worlds bounds will be adjusted to match the aspect ratio of the screen area.
void	removeMapBoundsListener(MapBoundsListener listener)
void	setBounds(ReferencedEnvelope requestedBounds) Sets the display area in world coordinates.
void	setCoordinateReferenceSystem(CoordinateReferenceSystem crs) Set the CoordinateReferenceSystem for the viewport.
void	setEditable(boolean editable) Sets whether the value of this viewport's attributes can be changed.
void	setMatchingAspectRatio(boolean enabled) Sets whether to adjust input world bounds to match the aspect ratio of the screen area.
void	setScreenArea(Rectangle screenArea) Sets the display area in screen (window, image) coordinates.

Methods inherited from class Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Field Detail

LOGGER

protected static final Logger LOGGER

The logger for the map module.

Constructor Detail

MapViewport

public MapViewport()

Creates a new view port. Screen area and world bounds will be empty, and aspect ratio matching will be disabled.

MapViewport

public MapViewport(boolean matchAspectRatio)

Creates a new view port. Screen area and world bounds will be empty.

Parameters:

matchAspectRatio - whether to enable aspect ratio matching

MapViewport

public MapViewport(ReferencedEnvelope bounds)

Creates a new view port with the specified display area in world coordinates. The input envelope is copied so subsequent changes to it will not affect the viewport.

The initial screen area will be empty and aspect ratio matching will be disabled.

Parameters:

bounds - display area in world coordinates (may be null)

MapViewport

public MapViewport(ReferencedEnvelope bounds,
                   boolean matchAspectRatio)

Creates a new viewport with the specified world bounds. The input envelope is copied so subsequent changes to it will not affect the viewport.

The initial screen area will be empty.

Parameters:

bounds - display area in world coordinates (may be null)

matchAspectRatio - whether to enable aspect ratio matching

MapViewport

public MapViewport(MapViewport sourceViewport)

Creates a new viewport based on an existing instance. The world bounds, screen area and aspect ratio matching setting of sourceViewport are copied.

Note: The new viewport will be editable even if sourceViewport is not editable.

Parameters:

sourceViewport - the viewport to copy

Throws:

IllegalArgumentException - if viewport is null

Method Detail

isEditable

public boolean isEditable()

Tests whether this viewport's attributes can be changed. Viewports are editable by default. A non-editable viewport will not allow the value of any of its attributes to be changed and will issue a log message (fine level) on any attempt to do so.

Returns:

true if this viewport is editable

setEditable

public void setEditable(boolean editable)

Sets whether the value of this viewport's attributes can be changed. Viewports are editable by default.

Parameters:

editable - true to allow changes

setMatchingAspectRatio

public void setMatchingAspectRatio(boolean enabled)

Sets whether to adjust input world bounds to match the aspect ratio of the screen area.

Parameters:

enabled - whether to enable aspect ratio adjustment

isMatchingAspectRatio

public boolean isMatchingAspectRatio()

Queries whether input worlds bounds will be adjusted to match the aspect ratio of the screen area.

Returns:

true if enabled

addMapBoundsListener

public void addMapBoundsListener(MapBoundsListener listener)

Used by client application to track the bounds of this viewport.

Parameters:

listener -

removeMapBoundsListener

public void removeMapBoundsListener(MapBoundsListener listener)

isEmpty

public boolean isEmpty()

Checks if the view port bounds are empty (undefined). This will be true if either or both of the world bounds and screen bounds are empty.

Returns:

true if empty

getBounds

public ReferencedEnvelope getBounds()

Gets the display area in world coordinates.

Note Well: this only covers spatial extent; you may wish to use the user data map to record the current viewport time or elevation.

Returns:

a copy of the current bounds

setBounds

public void setBounds(ReferencedEnvelope requestedBounds)

Sets the display area in world coordinates.

If bounds is null or empty, default identity coordinate transforms will be set.

If bounds is not empty, and aspect ratio matching is enabled, the coordinate transforms will be calculated to centre the requested bounds in the current screen area (if defined), after which the world bounds will be adjusted (enlarged) as required to match the screen area's aspect ratio.

A MapBoundsEvent will be fired to inform listeners of the change from old to new bounds. Note that when aspect ratio matching is enabled, the new bounds carried by the event will be the viewport's adjusted bounds, not the originally requested bounds.

Parameters:

requestedBounds - the requested bounds (may be null)

getScreenArea

public Rectangle getScreenArea()

Gets a copy of the current screen area.

Returns:

screen area to render into when drawing.

setScreenArea

public void setScreenArea(Rectangle screenArea)

Sets the display area in screen (window, image) coordinates.

Parameters:

screenArea - display area in screen coordinates (may be null)

getCoordinateReferenceSystem

public CoordinateReferenceSystem getCoordinateReferenceSystem()

The coordinate reference system used for rendering the map. If not yet set, null is returned.

The coordinate reference system used for rendering is often considered to be the "world" coordinate reference system; this is distinct from the coordinate reference system used for each layer (which is often data dependent).

Returns:

coordinate reference system used for rendering the map (may be null).

setCoordinateReferenceSystem

public void setCoordinateReferenceSystem(CoordinateReferenceSystem crs)

Set the CoordinateReferenceSystem for the viewport. If crs is null, the existing reference system will be discarded.

Parameters:

crs - the new coordinate reference system, or null for no reference system

fireMapBoundsListenerMapBoundsChanged

protected void fireMapBoundsListenerMapBoundsChanged(MapBoundsEvent.Type type,
                                                     ReferencedEnvelope oldBounds,
                                                     ReferencedEnvelope newBounds)

Notifies MapBoundsListeners about a change to the bounds or crs.

Parameters:

event - The event to be fired

getScreenToWorld

public AffineTransform getScreenToWorld()

Gets the current screen to world coordinate transform.

Returns:

a copy of the current screen to world transform or null if the transform is not set

getWorldToScreen

public AffineTransform getWorldToScreen()

Gets the current world to screen coordinate transform.

Returns:

a copy of the current world to screen transform or null if the transform is not set