org.hd.d.pg2k.webSvr.virtualHosts.AlohaEarth
Class AEParams

java.lang.Object
  org.hd.d.pg2k.webSvr.virtualHosts.AlohaEarth.AEParams

All Implemented Interfaces:

java.io.Serializable, java.lang.Cloneable

public final class AEParams
extends java.lang.Object
implements java.io.Serializable, java.lang.Cloneable

JavaBean used to parse/validate/adjust/save view parameters. This can have the zoom and (x,y)-offset parameters of a particular view set in various ways, and will coerce them to valid values. This can also be used to generate suitably-encoded parameters for a visitor to navigate in the Aloha Earth space.

So that this is a valid JavaBean we make it Serializable, but in practice never expect it to be persisted, even temporarily in a session, so we don't bother with a unique serialisation ID, validation, etc, but we do make any derived internal values transient.

This is NOT currently designed to be thread-safe.

This implements Clonable to as to make it possible to easily take a copy of the parameters, alter them, and turn the new values into a form's parameter set, for example.

The main parameters held in this bean are:

• The zoom factor: the amount the original image is zoomed in/out for display to the user. Bigger numbers mean more zoom in, ie greater expansion.
• The offset of the center of the (zoomed, shifted) image shown to the user north and east from the original image (which is centered on 0N OE).

Note that for the East Offset and North Offset, the offset is measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

The unit of measure is pixels of the original image, making the units invariant wrt the zoom factor of the current image, and thus this value is constrained to lie in the range [-BASE_2D_EARTH_MAP_WIDTH/2, +BASE_2D_EARTH_MAP_WIDTH/2] for EO, and [-BASE_2D_EARTH_MAP_HEIGHT/2, +BASE_2D_EARTH_MAP_HEIGHT/2] for NO though usually within a narrower range than that.

Note that the fact that when we zoom in one pixel in the original takes several pixels in the current/displayed image means that careful handling is required to get image alignment correct.

See Also:

Serialized Form

FORCE_TILE_POSITIONING

public static final boolean FORCE_TILE_POSITIONING

If true, round offset values to "tile" multiples. This ensures that fewer unique views can be seen, which should make cacheing feasable.

Across each view in each direction (E and N) are ZOOM_RATIO tiles. A user may move laterally in either dimension one tile width, and may zoom in to one of the tiles of the current image. Plainly, tiles from adjacent "windows" can in principle be shared, which we might make use of explicitly with a tiled display in HTML, or implicitly by say having JAI draw the image on demand and have a Renderable in cache.

See Also:

Constant Field Values

NAME_MAP_FIELD

public static final java.lang.String NAME_MAP_FIELD

Field name for map image as mouse-sensitive submit button. If the user clicks on the map image, we should receive a pair of [name].x and [name].y parameters of where the user clicked.

See Also:

Constant Field Values

MAP_CLICK_ZF_ADJ

public static final int MAP_CLICK_ZF_ADJ

Amount to add to zoomFactor on clicking on the map image; 0 means no zoom.

See Also:

Constant Field Values

NAME_ZOOM_CONTROL_FIELD

public static final java.lang.String NAME_ZOOM_CONTROL_FIELD

Name of zoom-control field (submit button). This, if set, carries changes to be applied after the zoom factor has been set from the NAME_ZOOM_FACTOR parameter.

See Also:

Constant Field Values

NAME_ZOOM_FACTOR

public static final java.lang.String NAME_ZOOM_FACTOR

External name of zoomFactor parameter, eg in HTTP GET/POST.

See Also:

Constant Field Values

zoomFactor

private int zoomFactor

The current zoom factor. Constrained to lie between MIN_ZOOM and MAX_ZOOM inclusive, and INITIAL_ZOOM unless otherwise set (ie the initial value).

OFFSET_LIMIT_EAST

public static final int OFFSET_LIMIT_EAST

The absolute maximum limit (+/-) of the East Offset in pixels; positive and rounded down.

See Also:

Constant Field Values

OFFSET_LIMIT_NORTH

public static final int OFFSET_LIMIT_NORTH

The absolute maximum limit (+/-) of the NORTH Offset in pixels; positive and rounded down.

See Also:

Constant Field Values

NAME_NORTH_OFFSET

public static final java.lang.String NAME_NORTH_OFFSET

External name of North Offset parameter, eg in HTTP GET/POST.

See Also:

Constant Field Values

NAME_EAST_OFFSET

public static final java.lang.String NAME_EAST_OFFSET

External name of East Offset parameter, eg in HTTP GET/POST.

See Also:

Constant Field Values

eastOffset

private int eastOffset

The East Offset of of the current view from original image. The offset is measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_WIDTH/2, +BASE_2D_EARTH_MAP_WIDTH/2].

The initial value is zero.

northOffset

private int northOffset

The North Offset of of the current view from original image. As the centre of the user's view goes more north, this becomes more positive.

The offset of measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_HEIGHT/2, +BASE_2D_EARTH_MAP_HEIGHT/2].

Note that is is the negative of the change in the y axis which in computer graphics usually has higher values lower down.

The initial value is zero.

PARAMS_PREFIX

private static final java.lang.String PARAMS_PREFIX

Prefix for (first) path component for embedded parameters, in the order prefix/e/n/z.

See Also:

Constant Field Values

PARAMS_PREFIX_NOT_IN_PATHINFO

private static final boolean PARAMS_PREFIX_NOT_IN_PATHINFO

If true then the PARAMS_PREFIX will not be visible in the path info.

See Also:

Constant Field Values

serialVersionUID

private static final long serialVersionUID

Unique Serialisation class ID generated by http://random.hd.org/.

See Also:

Constant Field Values

AEParams

public AEParams()

getZoomFactor

public int getZoomFactor()

Get the current zoom factor. Constrained to lie between MIN_ZOOM and MAX_ZOOM inclusive, and INITIAL_ZOOM unless otherwise set.

setZoomFactor

public AEParams setZoomFactor(int zf)

Set the current zoom factor as an integer; will be coerced to range. Constrained to lie between MIN_ZOOM and MAX_ZOOM inclusive, and the value will be coerced to those limits.

Returns:

reference to this modified object

setZoomFactor

public AEParams setZoomFactor(java.lang.String zf)

Set the current value as a String; parse and coerced as necessary. Parsed as a decimal (possibly-signed) integer and constrained to lie between MIN_ZOOM and MAX_ZOOM inclusive, and the value will be coerced to those limits.

In case of a parse error (including a null argument) no value is set.

Returns:

reference to this modified object

setEastOffset

public AEParams setEastOffset(int pixelsOffset)

Set the East Offset of the current view from the base/original image. As the centre of the user's view goes more east, this becomes more positive.

The offset of measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_WIDTH/2, +BASE_2D_EARTH_MAP_WIDTH/2]; any value outside these bounds is coerced to range.

When read back "constrained" this is coerced to try to keep the current view within the original source image.

The initial (unset/default) value is zero.

Returns:

reference to this modified object

setEastOffset

public AEParams setEastOffset(java.lang.String pixelsOffset)

Set East offset as String. Unparseable (or null) values are ignored, parseable values are coerced to fit the valid range.

Returns:

reference to this modified object

setNorthOffset

public AEParams setNorthOffset(int pixelsOffset)

Set the North Offset of the current view from the base/original image. As the centre of the user's view goes more north, this becomes more positive.

The offset of measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_HEIGHT/2, +BASE_2D_EARTH_MAP_HEIGHT/2]; any value outside these bounds is coerced to range.

When read back "constrained" this is coerced to try to keep the current view within the original source image.

The initial (unset/default) value is zero.

Returns:

reference to this modified object

setNorthOffset

public AEParams setNorthOffset(java.lang.String pixelsOffset)

Set North offset as String. Unparseable (or null) values are ignored, parseable values are coerced to fit the valid range.

Returns:

reference to this modified object

getEastOffset

public int getEastOffset(boolean constrained)

Get East Offset of the current view from the base/original image. As the centre of the user's view goes more east, this becomes more positive.

The offset of measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_WIDTH/2, +BASE_2D_EARTH_MAP_WIDTH/2] at most.

If called for a "constrained" value, the return is clamped so as to ensure that all of the current view lies within the base image if possible. In all cases the result, if adjusted, is adjusted towards zero.

If we are rounding to tile widths, we round down.

The initial value is zero.

Parameters:

constrained - if true, return is if necessary adjusted towards zero to try to force the current zoomed view to be from entirely within the source image and possibly rounded to a tile width, else the raw (but still clamped) value is returned

getEastOffsetSrcPixelsX

private int getEastOffsetSrcPixelsX(boolean constrained)

Get source image left (x) coordinate. As the centre of the user's view goes more east, this becomes more positive.

This calls getEastOffset().

Parameters:

constrained - if true, the result is always within the source image bounds [0,BASE_2D_EARTH_MAP_WIDTH-1] inclusive and if FORCE_TILE_POSITIONING is true will be rounded to a tile size

getNorthOffset

public int getNorthOffset(boolean constrained)

Get North Offset of the current view from original image. As the centre of the user's view goes more north, this becomes more positive.

The offset of measured from the centre of the current image to the centre of the original underlying image, where either centre may potentially lie within a pixel or between pixels.

This value is constrained to lie in the range [-BASE_2D_EARTH_MAP_HEIGHT/2, +BASE_2D_EARTH_MAP_HEIGHT/2] at most.

Note that is is the negative of the change in the y axis which in computer graphics usually has higher values lower down.

The initial value is zero.

Parameters:

constrained - if true, return is if necessary adjusted towards zero to try to force the current zoomed view to be from entirely within the source image, else the raw (but still clamped) value is returned

getNorthOffsetSrcPixelsY

private int getNorthOffsetSrcPixelsY(boolean constrained)

Get source image top (y) coordinate. As the centre of the user's view goes more north, this becomes more negative.

This calls getNorthOffset().

Parameters:

constrained - if true, the result is always within the source image bounds [0,BASE_2D_EARTH_MAP_HEIGHT-1] inclusive and if FORCE_TILE_POSITIONING is true will be rounded to a tile size

getEastDegrees

public float getEastDegrees(boolean constrained)

Get East Offset as degrees East; range approximately [-180f, +180f]. As the centre of the user's view goes more east, this becomes more positive.

The conversion will be a bit lumpy and inexact, especially as the underlying step in the offset is likely to be similar but not identical to a degree. The caller could usefully round this.

Clamped to +/- Location.Estd.MAX_E.

Parameters:

constrained - when true, if the source image area would lie partly or completely outside the base image, this is adjusted in line with getEastOffset() towards zero to try to bring it within the base image

getNorthDegrees

public float getNorthDegrees(boolean constrained)

Get North Offset as degrees North; range approximately [-90f, +90f]. As the centre of the user's view goes more north, this becomes more positive.

The conversion will be a bit lumpy and inexact, especially as the underlying step in the offset is likely to be similar but not identical to a degree. The caller could usefully round this.

Clamped to +/- Location.Estd.MAX_N.

getLocation

public Location.Estd getLocation(boolean constrained)

Get current offset as a Location.Estd; never null. The error bounds indicate the area covered by the current view.

getDisplayPixelForEstdLocationCentre

public java.awt.Point getDisplayPixelForEstdLocationCentre(Location.Estd targetLoc)

Gets pixel in current view corresponding to centre of given location; null if not in current view.

Parameters:

targetLoc - location to find pixel for centre of; null if not visible

computeXfromE

int computeXfromE(float targetE)

Compute X pixel from E degrees given current view; may not be visible.

computeYfromN

int computeYfromN(float targetN)

Compute Y pixel from N degrees given current view; may not be visible.

getSourceRectangleToDisplay

public java.awt.Rectangle getSourceRectangleToDisplay()

Get bounding rectangle of area to be zoomed to make display image. Specified in pixels of the original image.

Depends on zoom and offsets.

Clamped so that no part of this will lie outside the original image, but this may change the aspect ratio, for example.

The width and height are always strictly positive.

Note that we adjust the zoom we use so that the minimum allowable zoom shows the whole image, but shunk or expanded from the raw image if the MIN_ZOOM is non-zero.

getBaseSrcPixelsHeight

public int getBaseSrcPixelsHeight(boolean constrained)

Get height of current zoomed view in terms of original base-image pixels; always positive. Depends only on the zoom factor and does not (mutually) recurse with any of the the other accessor functions.

Parameters:

constrained - if true, the result is constrained to be no more than the height of the base image

getBaseSrcPixelsWidth

public int getBaseSrcPixelsWidth(boolean constrained)

Get width of current zoomed view in terms of original base-image pixels; always positive. Depends only on the zoom factor and does not (mutually) recurse with any of the the other accessor functions.

Parameters:

constrained - if true, the result is constrained to be no more than the width of the base image

getTileSrcPixelsWidth

public int getTileSrcPixelsWidth()

Get tile width in source-image pixels; strictly positive. Is the rounded-down current image width in source-image pixels divided by ZOOM_FACTOR, ie the number of steps left or right a user view is the same as the ratio by which we zoom in or out.

getTileSrcPixelsHeight

public int getTileSrcPixelsHeight()

Get tile height in source-image pixels; strictly positive. Is the rounded-down current image height in source-image pixels divided by ZOOM_FACTOR, ie the number of steps up or down a user view is the same as the ratio by which we zoom in or out.

adjustCentreWithXYClick

public void adjustCentreWithXYClick(int x,
                                    int y)

Adjusts East/North offsets given x,y coordinates of mouse click on displayed area. The x is allowed to range from [0,DISPLAY_2D_EARTH_MAP_WIDTH[ and y from [0,DISPLAY_2D_EARTH_MAP_HEIGHT[ with the effect of moving the centre offset of the image to be as close as possible to the source image pixel representing the displayed map-fragment pixel clicked on.

This assumes that the displayed map fragment has a constrained center and width/height.

Coerces values to allowed range if need be.

_negativeZoomFactor

private int _negativeZoomFactor()

Computes a negated zoom factor rebased to the minimum zoom. This is used to compute the actual source image width and height from which the displayed image is extracted and zoomed to size.

Returns:

non-positive factor

setRequest

public AEParams setRequest(javax.servlet.http.HttpServletRequest request)

Sets all parameters possible from a servlet request. Arguments are parsed and coerced to correct values or ignored if missing or badly broken, leaving previous values in place.

Where necessary, arguments are coerced to form a consistent set.

This coercion may depend on data gathered from the current exhibit data set and base clickable-map image can cached statically where we can get at it.

This first sets the basic values from their simple parameter values, the applies any adjustment implied by such things as the zoom control and/or the map (x,y) click location.

Returns:

reference to this modified object

setLocation

public AEParams setLocation(Location.Estd loc)

Set the best view to see the specified Location. Used to choose the view for a given area, eg in a link from a catalogue page.

This sets the (unconstrained) centre to be as close as possible to the specified location's centre.

This zooms in as far as it can to still totally enclose the target area in the putative map viewport.

getAsGetURLParameters

public java.lang.String getAsGetURLParameters(boolean constrained)

Gets parameters suitable to tag on to a URL after a '?', eg for GET operation. This is an easy way to build a link back to the page.

Ampersands ("&") separating parameters are expanded to entities, eg "x=3&y=2" for safety when embedded in HTML/XML text.

Note that this presents unconstrained parameters to preserve visitor's chosen offset as they zoom in and out.

Parameters:

constrained - if true, values returned are constrained to legal (and possibly tile) boundaries, which may help browser caching for example

getAsGetPathInfo

public java.lang.String getAsGetPathInfo(boolean constrained)

Gets parameters suitable to tag on to end of servlet URI to make new path. This is an easy way to build a link back to the page.

This is a URI suffix of the form "PREFIX/e/n/z" with no leading or trailing '/'.

Note that this presents unconstrained parameters to preserve visitor's chosen offset as they zoom in and out.

Parameters:

constrained - if true, values returned are constrained to legal (and possibly tile) boundaries, which may help browser caching for example

getAsHiddenFormElements

public java.lang.String getAsHiddenFormElements()

Gets parameters as hidden fields to include in a form. Note that this presents unconstrained parameters to preserve visitor's chosen offset as they zoom in and out.

toString

public java.lang.String toString()

Gets parameters as human-readable (albeit terse) String. Do not attempt to automatically parse this: the format may change without notice.

This includes key derived values too.

Overrides:

toString in class java.lang.Object

inDefaultState

public boolean inDefaultState()

Returns true if all values are as for initial state. This can be used to check that it is as if a visitor has newly arrived at the page with no parameters set, so the zoom, etc, are left at their default values.

clone

public java.lang.Object clone()

Clone this object; all state is separated from the original.

Overrides:

clone in class java.lang.Object

makeClone

public AEParams makeClone()

Make copy of this object; like clone() except no need to cast result. This is intended to be used with an idiom such as:

     makeCopy().setZoomFactor(newValue).getAsGetURLParameters()
 

to get a URL fragment for a link to change the zoom level.

cloneAndTranslate

public AEParams cloneAndTranslate(int eTiles,
                                  int nTiles)

Makes a clone and steps it by the requested number of tile units in each direction (East and North). Useful utility for JSP/servlet.

This coerces offsets to constrained values, which may help, for example, with cacheing by browsers and in the server, especially when tiling is being enforced.

makeKey

public java.lang.Object makeKey(boolean constrained)

Makes an immutable canonical key for use in a hash-table; never null. This is most valuable when FORCE_TILE_POSITIONING is true.

The result is produced from the zoom and unconstrained East and North offset values. This is unconstrained to allow for different target centroids even within a single view/tile.

The result supports equals() and hashCode but is otherwise to be considered opaque.

Parameters:

constrained - if true then the key is constrained to a coarser-grained grid of viewport coordinates