Package 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 Details

    • LOGGER

      protected static final Logger LOGGER
      The logger for the map module.

  • Constructor Details

    • 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 Details

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

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

    • 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

    • isFixedBoundsOnResize

      public boolean isFixedBoundsOnResize()
      Determine if the map retains its scale (false) or its bounds (true) when the MapPane is resized.

    • setFixedBoundsOnResize

      public void setFixedBoundsOnResize(boolean fixedBoundsOnResize)
      Determine if the map retains its scale (false) or its bounds (true) when the MapPane is resized.
      Parameters:
      fixedBoundsOnResize - - if true retain bounds on resize otherwise retain scale.