Package noaa.coastwatch.render

Class EarthDataView

java.lang.Object
noaa.coastwatch.render.EarthDataView
All Implemented Interfaces:
Cloneable, Renderable
Direct Known Subclasses:
ColorComposite, ColorEnhancement, HybridView, SolidBackground
public abstract class EarthDataView extends Object implements Renderable, Cloneable

The EarthDataView class sets up a correspondence between 2D Earth locatable data variables (possibly more than one) and a visual image. A view has a certain size in width and height and a translation between earth locations and image coordinates. A view may also have a number of data overlays for annotation. For a swath transform, the data view forces north to be in the upwards direction, at the top of the image. If the transform is such that data locations with larger indices have a greater latitude, the sense of the image transform is flipped so that north appears at the top.

A view maintains its image to data scaling information using the center data location and image scale factor. All view manipulations are relative to these quantities.

In order to help implement child classes, it may be of interest to developers to know how view rendering works. The main render() method is called by any user of the view to render the view to a graphics context. In some cases, this graphics context may be from a GUI panel on the screen, or in others it may be an offscreen image buffer that will be copied to the screen or saved to an image file. In either case, the render() method relies on a two-step process for rendering the view. It first renders the protected BufferedImage image variable to the graphics context. Secondly, it loops over each overlay in order and renders it to the graphics context. This two-step process may involve delays, both in rendering the main image and the overlays. For example, a delay may occur when translating data values into image colours, or in translating overlay earth locations to image coordinates.

In order to help handle delays, two protected variables are used: changed and progress. The changed flag indicates that something in the view has changed since the last time the render() method was called. If the view has changed, then any saved image buffer that was used to capture the results of the render() method may no longer be used and should be discarded. If the view has not changed, then rendering again will produce the exact same output and there is no need to render again if the output was saved. The progress flag indicates that the user wants to see progress updates during the delay in which the image is being rendered. In addition to these flags, the two methods prepare() and isPrepared() are used to determine how much of a delay may be involved in rendering. If the protected image variable is not built or one of the overlays is not ready to be immediately rendered in screen coordinates, then the view is "not prepared". The view may be explicitly prepared by calling the prepare() method and passing it the graphics context to which preparation progress should be written. Once prepared, the user may call render() and expect to have no delay.

To handle interruptions in rendering so that a user-interface using the view appears responsive, the stopRendering() method may be used. The method sets the protected stopRendering flag to indicate to the child class that it should stop inside any currently executing rendering loop and return. The isRendering() method may be used to determine if a rendering loop is currently active. Generally, these methods are only useful in a multithreaded application in which the rendering is running in a separate thread from the user-interface.

Since:
3.1.0
Author:
Peter Hollemans

  • Field Details

    • UPDATE_FRACTION

      public static final double UPDATE_FRACTION
      The update frequency as a fraction of the total image size. This should be used by any rendering routine that wants to show the progress of view construction while it is taking place.
      See Also:

    • trans

      protected EarthImageTransform trans
      The earth to image coordinate transform. This is used to translate between earth (lat,lon) and view image (x,y). It holds both the image transform for view image (x,y) to data (row,col) and the earth transform for data (row,col) to earth (lat,lon).

    • imageDims

      protected Dimension imageDims
      The view image dimensions. This is the height and width of the view graphics when delivered by the render() method.

    • overlays

      protected LinkedList<EarthDataOverlay> overlays
      A number of data overlays. The overlays are rendered in the view image after sorting according to level.

    • image

      protected BufferedImage image
      The buffered image used for rendering. The buffered image is used by child classes to render a specific image based on their own variables. This image is independent of the list of overlays and should only contain graphics specific to the child. It is subsequently used by this class to assemble the complete view graphics.

    • verbose

      protected boolean verbose
      The verbose mode flag. When true, the status of the main image rendering is printed, along with each overlay rendering step.

    • changed

      protected boolean changed
      The view changed flag, true if the view changed after rendering. The changed flag must be set if any change is made to the view that would change the view graphics generated by a call to the render() method.

    • progress

      protected boolean progress
      The rendering progress flag, true to show rendering progress. When rendering progress mode is on, the child class should periodically update the view graphics in the prepare() method at a frequency determined by UPDATE_FRACTION.

    • stopRendering

      protected boolean stopRendering
      The rendering stop flag, true to stop rendering in progress. This flag is set to false at the start of any rendering call, and should be used by child classes to break out of the rendering loop.

  • Constructor Details

    • EarthDataView

      protected EarthDataView(EarthDataView view)
      Creates a new view using the geometry of the specified view.
      Parameters:
      view - the view to copy.
      Since:
      3.7.1

    • EarthDataView

      protected EarthDataView(int[] dataDims, EarthTransform earthTrans) throws NoninvertibleTransformException
      Constructs a new view using the specified parameters. The view dimensions are initialized to the data dimensions, and the ratio of data to image pixel count to 1. A check is performed on the transform to determine if it should be oriented differently for display, and flipped or rotated if so. The verbose mode and progress mode flags are initially set to false.
      Parameters:
      dataDims - the data dimensions as [rows, columns].
      earthTrans - the earth transform.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

  • Method Details

    • getUpsideDown

      @Deprecated public boolean getUpsideDown()
      Deprecated.
      As of 3.3.1, use getOrientationAffine().
      Gets the upside-down flag.
      Returns:
      true if the view is being corrected from its normal orientation so that north is in the up direction, or false if not.

    • getOrientationAffine

      public AffineTransform getOrientationAffine()
      Gets the view orientation affine. The orientation affine transforms data coordinates for display, rotating or flipping as needed so that the north direction is at the top of the screen.
      Returns:
      the orientation affine (possibly the identity).
      Since:
      3.3.1

    • getImageAffine

      public AffineTransform getImageAffine()
      Gets the current image affine transform.
      Returns:
      the current transform or null for no transform.
      See Also:

    • setImageAffine

      public void setImageAffine(AffineTransform affine)
      Sets the image affine transform. When the view is rendered, the new image affine will be used to transform the image coordinates prior to rendering. Any overlays rendered will be unaffected.
      Parameters:
      affine - the image affine transform, or null for no transform.

    • stopRendering

      public void stopRendering()
      Sets the stop rendering flag to indicate that any current rendering loop should stop and return.

    • isRendering

      public boolean isRendering()
      Returns true if the view is currently being rendered, or false if not.

    • getOverlays

      public List<EarthDataOverlay> getOverlays()
      Gets the current list of overlays.

    • addOverlays

      public void addOverlays(List overlays)
      Adds a list of overlays to the view.

    • setVerbose

      public void setVerbose(boolean flag)
      Sets the verbose mode flag.

    • getProgress

      public boolean getProgress()
      Gets the rendering progress mode flag.

    • setProgress

      public void setProgress(boolean flag)
      Sets the rendering progress mode flag. When rendering progress mode is on, a call to render shows the progress of rendering by drawing successive images to the destination graphics device.

    • hasCoordinateCaches

      public boolean hasCoordinateCaches()
      Returns true if this view has coordinate caches available.
      See Also:

    • hasCompatibleCaches

      public boolean hasCompatibleCaches(Grid grid)
      Returns true if this view has coordinate caches that are compatible with the specified grid navigation transform. Returns false if the coordinate caches are incompatible or if there are no coordinate caches.
      See Also:

    • transform

      public int[] transform(Point p)
      Transforms an image point to an integer data location using precomputed coordinate caching.
      Parameters:
      p - the image point.
      Returns:
      the integer data location as [row, column]. This view must have coordinate caches available.
      See Also:

    • transform

      public void transform(Point p, int[] coords)
      Transforms an image point to an integer data location using precomputed coordinate caching.
      Parameters:
      p - the image point.
      coords - the output coordinates array. The array entries are modified to contain the integer data location as [row, column].
      See Also:

    • computeCaches

      public void computeCaches(Grid grid)
      Creates a set of caches to speed image-to-data transforms. The navigation transform of the specified grid is taken into account in the cache. Note that this is only useful when the navigation is either the identity or a translation.
      Parameters:
      grid - the grid variable to use for navigation corrections, or null to compute caches without any navigation transform.
      Since:
      Public as of 3.5.1, and the grid parameter may now be null if desired.

    • setChanged

      public void setChanged()
      Sets the changed flag. This method should be called if some existing overlay property has been updated, or some other change made to the view that would require the view buffer to be updated. Normally, the change flag is set internally but in some cases it may be necessary to "force" the view to acknowledge a change.

    • invalidate

      public void invalidate()
      Invalidates the view. This causes the view to be completely reconstructed upon the next call to render().

    • addOverlay

      public void addOverlay(EarthDataOverlay overlay)
      Adds an overlay to the view.

    • removeOverlay

      public void removeOverlay(EarthDataOverlay overlay)
      Removes an overlay from the view.

    • containsOverlay

      public boolean containsOverlay(EarthDataOverlay overlay)
      Checks if this view contains the specified overlay.

    • getTransform

      public EarthImageTransform getTransform()
      Gets the earth image transform.

    • getCorners

      @Deprecated public DataLocation[] getCorners()
      Deprecated.
      As of 3.3.1, use getBounds().
      Gets the data corners of this view as [upperLeft, lowerRight].

    • getBounds

      public DataLocation[] getBounds()
      Gets the bounds of this view.
      Returns:
      the array of data location bounds as [minimum(row,col), maximum(row,col)].
      Since:
      3.3.1

    • getCenter

      public DataLocation getCenter()
      Gets the center data location of this view.

    • getScale

      public double getScale()
      Gets the scale of this view.
      Returns:
      the ratio of data pixels to view image pixels.

    • getArea

      public EarthArea getArea()
      Gets the geographic area of this view.

    • setCenter

      public void setCenter(DataLocation center) throws NoninvertibleTransformException
      Sets the view center to a new data location. The image dimensions and image scaling factor are unaffected.
      Parameters:
      center - the new center data location.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • setCenterAndScale

      public void setCenterAndScale(DataLocation center, double scale) throws NoninvertibleTransformException
      Set the center and scale of this view
      Parameters:
      center - the new center data location.
      scale - the new scaling factor for the view (desired ratio of data pixels to image pixels).
      Throws:
      NoninvertibleTransformException
      See Also:

    • setProperties

      public void setProperties(EarthDataView view)
      Sets the properties of this view based on the specified view. The two views should have compatible earth transforms and data grids. The overlays, earth transform, and verbose mode are all copied.
      Parameters:
      view - the source view to copy properties from.

    • resizeMaxAspect

      public void resizeMaxAspect(int imageSize) throws NoninvertibleTransformException
      Changes the view size to the specified maximum dimension. The view dimensions are changed, as well as the data to image scaling so that approximately the same data is displayed in the resized view. The center data location is unaffected.
      Parameters:
      imageSize - the new image maximum dimension.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • resizeWidth

      public void resizeWidth(int imageWidth) throws NoninvertibleTransformException
      Changes the view size to the specified width. The view dimensions are changed, as well as the data to image scaling so that approximately the same data is displayed in the resized view. The center data location is unaffected.
      Parameters:
      imageWidth - the new image width.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • resizeHeight

      public void resizeHeight(int imageHeight) throws NoninvertibleTransformException
      Changes the view size to the specified height. The view dimensions are changed, as well as the data to image scaling so that approximately the same data is displayed in the resized view. The center data location is unaffected.
      Parameters:
      imageHeight - the new image height.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • resize

      public void resize(Dimension imageDims) throws NoninvertibleTransformException
      Changes the view size to the specified dimensions. The view dimensions are changed, as well as the data to image scaling so that approximately the same data is displayed in the resized view. The center data location is unaffected.
      Parameters:
      imageDims - the new image dimensions.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • resize

      public void resize(double factor) throws NoninvertibleTransformException
      Changes the view size by the specified factor. The view dimensions are changed, as well as the data to image scaling so that the same data is displayed in the resized view. The center data location is unaffected.
      Parameters:
      factor - the factor by which to change the view size. Factors greater than 1 increase the view size and factors less than 1 decrease the view size.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • magnify

      public void magnify(DataLocation center, double factor) throws NoninvertibleTransformException
      Magnifies this view around a center location. The view dimensions are unaffected.
      Parameters:
      center - the new center data location.
      factor - the factor by which to magnify. Factors greater than 1 increase the magnification and factors less than 1 decrease the magnification.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • magnify

      public void magnify(double factor) throws NoninvertibleTransformException
      Magnifies this view around the current center location. The view dimensions are unaffected.
      Parameters:
      factor - the factor by which to magnify. Factors greater than 1 increase the magnification and factors less than 1 decrease the magnification.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.
      See Also:

    • magnify

      public void magnify(Point upperLeft, Point lowerRight) throws NoninvertibleTransformException
      Magnifies the specified area to occupy the entire view. The center data location is changed to match the center of the specified rectangle. The scaling factor is changed so that the maximum dimension of the rectangle fits within the view dimensions.
      Parameters:
      upperLeft - the upper-left corner point.
      lowerRight - the lower-right corner point.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • reset

      public void reset() throws NoninvertibleTransformException
      Resets the view to the full data resolution. The center data location is reset to the center of the data, the image:data scaling factor to 1, and the image dimensions to the full data dimensions.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • setSize

      public void setSize(Dimension imageDims) throws NoninvertibleTransformException
      Sets the view to a new size. The data center location and image scaling factor remain unaffected.
      Parameters:
      imageDims - the new image dimensions.
      Throws:
      NoninvertibleTransformException - if the image to data transform is not invertible.

    • getResolution

      public double getResolution()
      Calculates the view resolution at the center data location in km/pixel.
      Returns:
      the resolution in km/pixel.

    • prepare

      protected abstract void prepare(Graphics2D g)
      Prepares this view for rendering using the specified graphics object. This method is called when any changes have occurred that require the view to be completely reconstructed, such as a change in view size or data window.

    • isPrepared

      public boolean isPrepared()
      Gets the status of view and overlay preparation. If the view is prepared, a render call will return after almost no delay. If not, the render may require time to complete due to loading data from disk or cache, converting earth locations to screen points, and so on.

    • isChanged

      public boolean isChanged()
      Gets the status of the view changed flag. If the view is modified after rendering by resizing or changing overlays, then the view is changed and may require re-rendering.

    • render

      public void render(Graphics2D g)
      Renders this view using the graphics object.
      Specified by:
      render in interface Renderable
      Parameters:
      g - the graphics context for rendering.

    • getLegend

      public Legend getLegend()
      Gets a legend for annotation of the data view. This default method returns null, but subclasses may override this method to provide a legend.
      Returns:
      a legend or null if no legend is available.

    • getSize

      public Dimension getSize(Graphics2D g)
      Gets the rendered view dimensions.
      Specified by:
      getSize in interface Renderable
      Parameters:
      g - the graphics context for rendering. In this class, the graphics context is ignored and may be null.
      Returns:
      the rendered view dimensions.

    • clone

      public Object clone()
      Creates and returns a copy of this object. Child classes should override this method if they contain any deep structure that needs copying.
      Overrides:
      clone in class Object

    • showSubregion

      @Deprecated public void showSubregion(Subregion subregion)
      Deprecated.
      Magnifies this view to show the specified subregion. If the limits of the subregion cannot be determined for the view, no operation is performed.
      Parameters:
      subregion - the subregion to show.
      See Also:

    • getSubregion

      @Deprecated public Subregion getSubregion()
      Deprecated.
      Gets the subregion currently displayed by this view.
      Returns:
      the subregion displayed.
      See Also:

    • main

      public static void main(String[] argv) throws Exception
      Tests this class.
      Parameters:
      argv - the array of command line parameters.
      Throws:
      Exception