public abstract class EarthDataView extends java.lang.Object implements Renderable, java.lang.Cloneable
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 involed 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.
Modifier and Type | Field and Description |
---|---|
protected boolean |
changed
The view changed flag, true if the view changed after rendering.
|
protected java.awt.image.BufferedImage |
image
The buffered image used for rendering.
|
protected java.awt.Dimension |
imageDims
The view image dimensions.
|
protected java.util.LinkedList<EarthDataOverlay> |
overlays
A number of data overlays.
|
protected boolean |
progress
The rendering progress flag, true to show rendering progress.
|
protected boolean |
stopRendering
The rendering stop flag, true to stop rendering in progress.
|
protected EarthImageTransform |
trans
The earth to image coordinate transform.
|
static double |
UPDATE_FRACTION
The update frequency as a fraction of the total image size.
|
protected boolean |
verbose
The verbose mode flag.
|
Modifier | Constructor and Description |
---|---|
protected |
EarthDataView(int[] dataDims,
EarthTransform earthTrans)
Constructs a new earth data view using the specified parameters.
|
Modifier and Type | Method and Description |
---|---|
void |
addOverlay(EarthDataOverlay overlay)
Adds an overlay to the view.
|
void |
addOverlays(java.util.List overlays)
Adds a list of overlays to the view.
|
java.lang.Object |
clone()
Creates and returns a copy of this object.
|
protected void |
computeCaches(Grid grid)
Creates a set of caches to speed image-to-data transforms.
|
boolean |
containsOverlay(EarthDataOverlay overlay)
Checks if this view contains the specified overlay.
|
EarthArea |
getArea()
Gets the geographic area of this view.
|
DataLocation[] |
getBounds()
Gets the bounds of this view.
|
DataLocation |
getCenter()
Gets the center data location of this view.
|
DataLocation[] |
getCorners()
Deprecated.
As of 3.3.1, use
getBounds() . |
java.awt.geom.AffineTransform |
getImageAffine()
Gets the current image affine transform.
|
Legend |
getLegend()
Gets a legend for annotation of the data view.
|
java.awt.geom.AffineTransform |
getOrientationAffine()
Gets the view orientation affine.
|
java.util.List<EarthDataOverlay> |
getOverlays()
Gets the current list of overlays.
|
boolean |
getProgress()
Gets the rendering progress mode flag.
|
double |
getResolution()
Calculates the view resolution at the center data location in
km/pixel.
|
double |
getScale()
Gets the scale of this view.
|
java.awt.Dimension |
getSize(java.awt.Graphics2D g)
Gets the rendered view dimensions.
|
Subregion |
getSubregion()
Deprecated.
|
EarthImageTransform |
getTransform()
Gets the earth image transform.
|
boolean |
getUpsideDown()
Deprecated.
As of 3.3.1, use
getOrientationAffine() . |
boolean |
hasCompatibleCaches(Grid grid)
Returns true if this view has coordinate caches that are
compatible with the specified grid navigation transform.
|
boolean |
hasCoordinateCaches()
Returns true if this view has coordinate caches available.
|
void |
invalidate()
Invalidates the view.
|
boolean |
isChanged()
Gets the status of the view changed flag.
|
boolean |
isPrepared()
Gets the status of view and overlay preparation.
|
boolean |
isRendering()
Returns true if the view is currently being rendered, or false
if not.
|
void |
magnify(DataLocation center,
double factor)
Magnifies this view around a center location.
|
void |
magnify(double factor)
Magnifies this view around the current center location.
|
void |
magnify(java.awt.Point upperLeft,
java.awt.Point lowerRight)
Magnifies the specified area to occupy the entire view.
|
static void |
main(java.lang.String[] argv)
Tests this class.
|
protected abstract void |
prepare(java.awt.Graphics2D g)
Prepares this view for rendering using the specified graphics
object.
|
void |
removeOverlay(EarthDataOverlay overlay)
Removes an overlay from the view.
|
void |
render(java.awt.Graphics2D g)
Renders this view using the graphics object.
|
void |
reset()
Resets the view to the full data resolution.
|
void |
resize(java.awt.Dimension imageDims)
Changes the view size to the specified dimensions.
|
void |
resize(double factor)
Changes the view size by the specified factor.
|
void |
resizeHeight(int imageHeight)
Changes the view size to the specified height.
|
void |
resizeMaxAspect(int imageSize)
Changes the view size to the specified maximum dimension.
|
void |
resizeWidth(int imageWidth)
Changes the view size to the specified width.
|
void |
setCenter(DataLocation center)
Sets the view center to a new data location.
|
void |
setCenterAndScale(DataLocation center,
double scale)
Set the center and scale of this view
|
void |
setChanged()
Sets the changed flag.
|
void |
setImageAffine(java.awt.geom.AffineTransform affine)
Sets the image affine transform.
|
void |
setProgress(boolean flag)
Sets the rendering progress mode flag.
|
void |
setProperties(EarthDataView view)
Sets the properties of this view based on the specified view.
|
void |
setSize(java.awt.Dimension imageDims)
Sets the view to a new size.
|
void |
setVerbose(boolean flag)
Sets the verbose mode flag.
|
void |
showSubregion(Subregion subregion)
Deprecated.
|
void |
stopRendering()
Sets the stop rendering flag to indicate that any current
rendering loop should stop and return.
|
int[] |
transform(java.awt.Point p)
Transforms an image point to an integer data location using
precomputed coordinate caching.
|
void |
transform(java.awt.Point p,
int[] coords)
Transforms an image point to an integer data location using
precomputed coordinate caching.
|
public static final double UPDATE_FRACTION
protected EarthImageTransform trans
protected java.awt.Dimension imageDims
render()
method.protected java.util.LinkedList<EarthDataOverlay> overlays
protected java.awt.image.BufferedImage image
protected boolean verbose
protected boolean changed
render()
method.protected boolean progress
prepare()
method at a frequency determined by
UPDATE_FRACTION
.protected boolean stopRendering
protected EarthDataView(int[] dataDims, EarthTransform earthTrans) throws java.awt.geom.NoninvertibleTransformException
dataDims
- the data dimensions as [rows, columns].earthTrans
- the earth transform.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.@Deprecated public boolean getUpsideDown()
getOrientationAffine()
.public java.awt.geom.AffineTransform getOrientationAffine()
public java.awt.geom.AffineTransform getImageAffine()
setImageAffine(java.awt.geom.AffineTransform)
public void setImageAffine(java.awt.geom.AffineTransform affine)
affine
- the image affine transform, or null for no
transform.public void stopRendering()
public boolean isRendering()
public java.util.List<EarthDataOverlay> getOverlays()
public void addOverlays(java.util.List overlays)
public void setVerbose(boolean flag)
public boolean getProgress()
public void setProgress(boolean flag)
render
shows the progress of
rendering by drawing successive images to the destination
graphics device.public boolean hasCoordinateCaches()
transform(Point)
public boolean hasCompatibleCaches(Grid grid)
public int[] transform(java.awt.Point p)
p
- the image point.[row, column]
.
This view must have coordinate caches available.hasCoordinateCaches()
public void transform(java.awt.Point p, int[] coords)
p
- the image point.coords
- the output coordinates array. The array entries
are modified to contain the integer data location as [row,
column]
.hasCoordinateCaches()
protected void computeCaches(Grid grid)
grid
- the grid variable to use for navigation corrections.public void setChanged()
public void invalidate()
render()
.public void addOverlay(EarthDataOverlay overlay)
public void removeOverlay(EarthDataOverlay overlay)
public boolean containsOverlay(EarthDataOverlay overlay)
public EarthImageTransform getTransform()
@Deprecated public DataLocation[] getCorners()
getBounds()
.public DataLocation[] getBounds()
public DataLocation getCenter()
public double getScale()
public EarthArea getArea()
public void setCenter(DataLocation center) throws java.awt.geom.NoninvertibleTransformException
center
- the new center data location.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void setCenterAndScale(DataLocation center, double scale) throws java.awt.geom.NoninvertibleTransformException
center
- the new center data location.scale
- the new scaling factor for the view (desired ratio of
data pixels to image pixels).java.awt.geom.NoninvertibleTransformException
getCenter()
public void setProperties(EarthDataView view)
view
- the source view to copy properties from.public void resizeMaxAspect(int imageSize) throws java.awt.geom.NoninvertibleTransformException
imageSize
- the new image maximum dimension.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void resizeWidth(int imageWidth) throws java.awt.geom.NoninvertibleTransformException
imageWidth
- the new image width.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void resizeHeight(int imageHeight) throws java.awt.geom.NoninvertibleTransformException
imageHeight
- the new image height.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void resize(java.awt.Dimension imageDims) throws java.awt.geom.NoninvertibleTransformException
imageDims
- the new image dimensions.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void resize(double factor) throws java.awt.geom.NoninvertibleTransformException
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.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void magnify(DataLocation center, double factor) throws java.awt.geom.NoninvertibleTransformException
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.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void magnify(double factor) throws java.awt.geom.NoninvertibleTransformException
factor
- the factor by which to magnify. Factors greater
than 1 increase the magnification and factors less than 1
decrease the magnification.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.magnify(DataLocation,double)
public void magnify(java.awt.Point upperLeft, java.awt.Point lowerRight) throws java.awt.geom.NoninvertibleTransformException
upperLeft
- the upper-left corner point.lowerRight
- the lower-right corner point.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void reset() throws java.awt.geom.NoninvertibleTransformException
java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public void setSize(java.awt.Dimension imageDims) throws java.awt.geom.NoninvertibleTransformException
imageDims
- the new image dimensions.java.awt.geom.NoninvertibleTransformException
- if the image to data
transform is not invertible.public double getResolution()
protected abstract void prepare(java.awt.Graphics2D g)
public boolean isPrepared()
public boolean isChanged()
public void render(java.awt.Graphics2D g)
render
in interface Renderable
g
- the graphics context for rendering.public Legend getLegend()
public java.awt.Dimension getSize(java.awt.Graphics2D g)
getSize
in interface Renderable
g
- the graphics context for rendering. In this class, the
graphics context is ignored and may be null.public java.lang.Object clone()
clone
in class java.lang.Object
@Deprecated public void showSubregion(Subregion subregion)
subregion
- the subregion to show.getSubregion()
@Deprecated public Subregion getSubregion()
showSubregion(noaa.coastwatch.render.Subregion)
public static void main(java.lang.String[] argv) throws java.lang.Exception
argv
- the array of command line parameters.java.lang.Exception