com.c5corp.c5utm
Class Points

java.lang.Object
  com.c5corp.c5utm.Points

public class Points
extends java.lang.Object

Points.java - part of Landscape database (otherwise known as the C5UTM database). A Points object is designed to hold a 2d array of com.c5corp.c5utm.Point objects, and a large collection of accessors and methods that describe or calculate descriptors of the area that is represented.
It provides constructor that you should never call, and accessor/calculator methods for all fields. Note that the methods prepended "calculate" must perform a calculation of that attribute the first time they are called, but will thereafter simply return a cached value. Some of these methods call other calculation methods of the same class.
You would not normally create and instance of this class yourself using new, but will instead use the static factory methods in the C5UTM class because they do some of the basic calculations for members of this class. (In particular, the lowest and highest elevations, the largest_col, building the 2d array from the database, and determining if there are void areas with in the requested area.) This factory method approach may seem counter intuitive from an OOP point of view, but this mirrors factory subroutines in C5UTM.pm, A perl module from which these java classes were spawned.
This class also provides a println method.
!!!! this is only partially implemented to match C5UTM.pm - particularly, not all of the calculate and find methods of C5UTM are yet implemented.

Since:

1.0

Author:

Brett Stalbaum Copyright 2002-2006 see LICENSE.txt and UCSD_LICENSE.txt

Field Summary

static int[]

CARDINAL_BITS CARDINAL_BITS, which also include intercardinal primary directions, are arranged declared in the array in the following order: {N_BIT,NE_BIT,E_BIT,SE_BIT,S_BIT,SW_BIT,W_BIT,NW_BIT}.

Constructor Summary

Points(int lowest, int highest, int largest_col, Point[][] array, int[] shape, boolean has_void, double percent_void)
public Points(int zone, int easting, int northing, int elevation, int id)

Method Summary

int	calculateClosestMean() Finds the actual elevation that is member of the Data Set which is closest to the actual mean.
int	calculateClosestMedian() Find the elevation in the Data Set closest to the median.
int	calculateContiguousModalityPercentage() Calculates the contiguous modality percentage.
java.util.HashMap	calculateFrequencyHash() Calculates and returns a java.util.HashMap object.
double	calculateMean() This method calculates the mean value of all elevations in the Points object.
double	calculateMedian() Calculates the median value of the elevations.
int[]	calculateMode() Calculates and returns an array int[] containing one or more (if multi-modal) modes for the area.
int	calculateNumberOfPoints() This is a calculation because there may be void areas.
int	calculatePercentile(int elevation) # calculatePercentile takes one argument, an elevation, and returns a value from 0 to 100 representing the percentile of that elevation relative to the rest of the set, or -1 or -2 -1 is a sentinel indicating that the area is flat, thus there is not a percentile to calculate -2 is a sentinel indicating that the elevation given is out of the range between highest and lowest Note that if it is a flat area, this function returns -1.
double	calculateStandardDeviation() Calculates and returns a java.util.HashMap object.
int	calculateSumOfElevations() This method returns the total sume of all of the elevations represented in the Points object.
int	calculateTerrainDescriptor() Characterizes the shape of the immediate surrounding area - the immediate points around the point.
int	calculateTopographyDescriptor() Characterizes the shape of a 1K area - Can be used to identify canyons, draws, spurs, ridges, valleys, depressions and saddles.
int	findClosestElevation(int val) find the elevation value in the Data Set closest to the param givin.
int[]	getArrayShape() Returns a simple array that can be used to iterate over the 2d array returned by getElevations.
int	getHighest() public int getHighest()
int	getLargestColumn() returns the size of the largest column - useful for imaging
int	getLowest() public int getLowest()
double	getPercentVoid() This function returns the percentage of undefined points to defined points.
Point	getPointAt(int x, int y) Returns the point at (X,Y) in the array, or throws an ArrayIndexOutOfBoundsException.
Point[][]	getPointsArray() Returns a reference to an array of arrays (a 2d array reference) of com.c5corp.c5utm.Point objects.
java.lang.String	getSWCorner() returns a String representation of the south west corner.
UtmCoordinatePairElev[][]	getUtmCoordinatePairElevArray() Returns a reference to an array of arrays (a 2d array reference) of com.c5corp.c5dem.UtmCoordinatePairElev objects.
boolean	hasVoidArea() public boolean hasVoidArea()
java.lang.String	toString() String representation of the Points object.

Methods inherited from class java.lang.Object

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

Field Detail

CARDINAL_BITS

public static final int[] CARDINAL_BITS

CARDINAL_BITS, which also include intercardinal primary directions, are arranged declared in the array in the following order: {N_BIT,NE_BIT,E_BIT,SE_BIT,S_BIT,SW_BIT,W_BIT,NW_BIT}. The array CARDINAL_BITS can be used to iterate over the values returned by int calculateTerrainDescriptor() and int calculateTopographyDescriptor() for analysis.

Constructor Detail

Points

public Points(int lowest,
              int highest,
              int largest_col,
              Point[][] array,
              int[] shape,
              boolean has_void,
              double percent_void)

public Points(int zone, int easting, int northing, int elevation, int id)

Constructor for the Point class. Normally you would not call this constructor yourself, but would use on of the static methods fo the C5UTM class to create an object of this type. The static methods of the C5UTM class makes an call to the database in which the related data from the UTM_COORDS table is taken and an instance of this class produced.

Parameters:

lowest - the low elevation

highest - the high elevation

largest_col - the size of the largest column

array - the array of Points[][]

shape - a 1D array describing array[][]

has_void - true if voids

percent_void - the percentage of voids

Method Detail

getLowest

public int getLowest()

public int getLowest()

Returns the lowest elevation found in the set - useful for imaging

Returns:

the elevation of the lowest point

getHighest

public int getHighest()

public int getHighest()

Returns the highest elevation found in the set - useful for imaging

Returns:

the elevation of the highest point

getLargestColumn

public int getLargestColumn()

returns the size of the largest column - useful for imaging

Returns:

the size of the largest column

getPointsArray

public Point[][] getPointsArray()

Returns a reference to an array of arrays (a 2d array reference) of com.c5corp.c5utm.Point objects. getArrayShape() returns an array describing each column in the 2d array where the array index represents the 'x' (thus the array length is number of cols), and the length of each col is the value of each index. Point 0,0 is the SW corner, easting to the x, northing to the y. This can be used to iterate over the Point[][].

Returns:

array the array of Points[][]

See Also:

Point

getUtmCoordinatePairElevArray

public UtmCoordinatePairElev[][] getUtmCoordinatePairElevArray()

Returns a reference to an array of arrays (a 2d array reference) of com.c5corp.c5dem.UtmCoordinatePairElev objects. This is an older com.c5corp.c5dem type, available here because it has some utility. However, it is preferable to use a Point[][] when possible, because this method converts the Points classes Point[][] object into a UtmCoordinatePairElev[][], throwing away some information. getArrayShape() returns an array describing each column in the 2d array where the array index represents the 'x' (thus the array length is number of cols), and the length of each col is the value of each index. Point 0,0 is the SW corner, easting to the x, northing to the y. This can be used to iterate over the UtmCoordinatePairElev[][].

Returns:

array the array as UtmCoordinatePairElev[][]

See Also:

getArrayShape(), getArrayShape(), UtmCoordinatePairElev, Point

getPointAt

public Point getPointAt(int x,
                        int y)
                 throws java.lang.ArrayIndexOutOfBoundsException

Returns the point at (X,Y) in the array, or throws an ArrayIndexOutOfBoundsException. It is possible to avoid this exception. See getArrayShape()

Parameters:

x - the x value

y - the y value

Returns:

the Point at x,y

Throws:

java.lang.ArrayIndexOutOfBoundsException

getArrayShape

public int[] getArrayShape()

Returns a simple array that can be used to iterate over the 2d array returned by getElevations. Note that the data returned from C5UTM is *not* always a regular x by y grid! (may contain null that represent voids. See also hasVoidArea()

Returns:

a 1D array describing array[][]

calculateMean

public double calculateMean()

This method calculates the mean value of all elevations in the Points object. Once this method has been called and the instance variable is calculated, it simply returns the value stored in the instance variable.

Returns:

the mean elevation

calculateNumberOfPoints

public int calculateNumberOfPoints()

This is a calculation because there may be void areas. This value is also calculated by calculateMean() and calculateSumOfElevations(). If those methods have been called on an object of this class, this value is pre-calculated and will be returned directly from an instance variable.

Returns:

number of points

calculateSumOfElevations

public int calculateSumOfElevations()

This method returns the total sume of all of the elevations represented in the Points object. This method is only marginally useful, and an especially problematic way to compare areas if some of the areas have voids. Basically, it only makes sense if the areas have the same number of points, This value is also calculated by calculateMean() If calculateMean() has been called on an object of this class. Once this value has been pre-calculated it will be returned directly from an instance variable.

Returns:

sum of all Point elevations

calculateMedian

public double calculateMedian()

Calculates the median value of the elevations. This method calls calculateNumberOfPoints() internally. Once this value has been pre-calculated it will be returned directly from an instance variable.

Returns:

the median elevation of all Points

calculateFrequencyHash

public java.util.HashMap calculateFrequencyHash()

Calculates and returns a java.util.HashMap object. The keys of the hash are Short Objects representing the elevation of a point in the Points array, and the value is an Short representing the number of occurances of the elevation represented by the key value.

Returns:

a HashMap of the elevation frequencies

calculateStandardDeviation

public double calculateStandardDeviation()

Calculates and returns a java.util.HashMap object. The keys of the hash are Short Objects representing the elevation of a point in the Points array, and the value is an Short representing the number of occurances of the elevation represented by the key value. Once this value has been pre-calculated it will be returned directly from an instance variable.

Returns:

the standard deviation of all Point elevations

calculateMode

public int[] calculateMode()

Calculates and returns an array int[] containing one or more (if multi-modal) modes for the area.

Returns:

the modal value of all Point elevations

calculateClosestMean

public int calculateClosestMean()

Finds the actual elevation that is member of the Data Set which is closest to the actual mean.

Returns:

the closest actual value to mean

calculateClosestMedian

public int calculateClosestMedian()

Find the elevation in the Data Set closest to the median. In some situations when there is an even list with two different values in the middle, the median is an average of those two values, usually a fraction and not a member of the set. This method maps to a memeber of the set. This is important when you expect the value to be a member of the set.

Returns:

the closest actual value to median

calculateContiguousModalityPercentage

public int calculateContiguousModalityPercentage()

Calculates the contiguous modality percentage. The cpm is the number of modal elevations that are contiguous with themselves ie, are 'next to" a point with the same (modal) elevation for that area this is to identify how much 'pooling' of the modal elevation(s) there is in the area.

Returns:

the cmp

findClosestElevation

public int findClosestElevation(int val)

find the elevation value in the Data Set closest to the param givin. This method does not cache it's result.

Parameters:

val -

Returns:

the elevation value

calculatePercentile

public int calculatePercentile(int elevation)

# calculatePercentile takes one argument, an elevation, and returns a value from 0 to 100 representing the percentile of that elevation relative to the rest of the set, or -1 or -2
-1 is a sentinel indicating that the area is flat, thus there is not a percentile to calculate
-2 is a sentinel indicating that the elevation given is out of the range between highest and lowest
Note that if it is a flat area, this function returns -1. -2 would infer that there is a range to be out of, which there is not given a flat area. Thus NO VALUE will ever return -2 'out of range' for a flat space. So you should check for this condition (perfect flatness), before you depend on this function to verify that a value is out of the area's range!
100 indicates the elevation given is == to the highest point in the area
0 indicates the elevation given is == to the lowest point in the area
-1, 0, and 100 are useful values for finding flat areas, basins or lowpoints on slopes, and peaks respectively if the value is not between the high and the low point in the set.

Parameters:

elevation - the elevation to evaluate

Returns:

the percentile (or -1, -2)

calculateTerrainDescriptor

public int calculateTerrainDescriptor()

Characterizes the shape of the immediate surrounding area - the immediate points around the point. Each bit refers to a direction, true indicating the terrain is higher in that direction, false indicating that it is equal to or lower terrain in that direction.
Bit order: NW, W, SW, S, SE, E, NE, N
Bit order: 128,64, 32, 16, 8, 4, 2, 1

Note that all the range of values will always be 0-255, in spite of this methods return type being an int. The terrain descriptor is thus fairly meaningless as a comparative basis unless you shift through each bit postion in order to find a match (at 0, 45, 90, 135, 180, 225, 270, and 315 degrees.) Returns -1 if the value can not be caluclated.

Returns:

the terrain descriptor for this

calculateTopographyDescriptor

public int calculateTopographyDescriptor()

Characterizes the shape of a 1K area - Can be used to identify canyons, draws, spurs, ridges, valleys, depressions and saddles. Each bit refers to a direction, true indicating the terrain is higher in that direction, false indicating that it is equal to or lower terrain in that direction.
Bit order: NW, W, SW, S, SE, E, NE, N
Bit order: 128,64, 32, 16, 8, 4, 2, 1

Note that all the range of values will always be 0-255, in spite of this methods return type being an int. The terrain descriptor is thus fairly meaningless as a comparative basis unless you shift through each bit postion in order to find a match (at 0, 45, 90, 135, 180, 225, 270, and 315 degrees.)

Returns:

the topography descriptor for this

toString

public java.lang.String toString()

String representation of the Points object.

Overrides:

toString in class java.lang.Object

getSWCorner

public java.lang.String getSWCorner()

returns a String representation of the south west corner.

Returns:

the SW corner info

hasVoidArea

public boolean hasVoidArea()

public boolean hasVoidArea()

This function returns true if the elevations area has any undefined points. (These would be points not in the database, or near the edges of really large sets where the curvature of the data causes clipping in due to the slight skew in the grid that can occur, (especially if converting points with corpscon...)

Returns:

true if the Points has voids

getPercentVoid

public double getPercentVoid()

This function returns the percentage of undefined points to defined points.

Returns:

the percentage of void points