com.klg.jclass.chart3d.data
Class JCData3dUtil

java.lang.Object
  |
  +--com.klg.jclass.chart3d.data.JCData3dUtil

All Implemented Interfaces:

SwingConstants

public class JCData3dUtil

extends Object

implements SwingConstants

Field Summary

static int	DATA_INTERPOLATE_CUBIC
static int	DATA_INTERPOLATE_LINEAR

Fields inherited from interface javax.swing.SwingConstants

BOTTOM, CENTER, EAST, HORIZONTAL, LEADING, LEFT, NEXT, NORTH, NORTH_EAST, NORTH_WEST, PREVIOUS, RIGHT, SOUTH, SOUTH_EAST, SOUTH_WEST, TOP, TRAILING, VERTICAL, WEST

Constructor Summary

JCData3dUtil()

Method Summary

static double	computeInverseWeightedAverage(double[] values, double[] weights, double centreWeight, int centreIndex, double holeValue) Generates a weighted average value for a data point based on its own value, as well as contributions from values contained in the values array.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createCubicSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, double[] xSamples, double[] ySamples) Constructs a data model by taking xSamples.length and ySamples.length samples along the x and y axes of the source.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createCubicSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, RectangularShape dataWindow, int xSampleSize, int ySampleSize) Constructs a data model by taking xSampleSize and ySampleSize samples along the x and y axes of the source.
static void	createCubicSplineCoefficients(double[] x, double[] y, double[] a, double[] b, double[] c, double[] d, int n) Fits a piecewise cubic spline to the series of x,y points.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createDataCopy(com.klg.jclass.chart3d.Chart3dGridDataModel source) Constructs a copy of the Chart3dGridDataModel source and returns it.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createLinearSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, double[] xSamples, double[] ySamples) Constructs a data model by taking xSamples.length and ySamples.length samples along the x and y axes of the source.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createLinearSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, RectangularShape dataWindow, int xSampleSize, int ySampleSize) Constructs a data model by taking xSampleSize and ySampleSize samples along the x and y axes of the source.
static void	createLinearSplineCoefficients(double[] x, double[] y, double[] a, double[] b, int n) Fits a piecewise linear spline to the series of x,y points.
static void	createShadedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, com.klg.jclass.chart3d.Chart3dGridDataModel dest, double sweepAngle, double riseAngle, double brightness, double ambient) Constructs an array of z values for the specified Chart3dGridDataModel source where each z value is a measurement of light on the closed range [0,1].
static com.klg.jclass.chart3d.Chart3dGridDataModel	createShadedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, double sweepAngle, double riseAngle, double brightness, double ambient) Constructs an array of z values for the specified Chart3dGridDataModel source where each z value is a measurement of light on the closed range [0,1].
static void	createSmoothedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, com.klg.jclass.chart3d.Chart3dGridDataModel dest, double centreWeight) Constructs a data model with a data surface with the same x and y grid values of source, but with "smoothed" z values.
static com.klg.jclass.chart3d.Chart3dGridDataModel	createSmoothedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source, double centreWeight) Constructs a data model with a data surface with the same x and y grid values of source, but with "smoothed" z values.
static void	dataCopy(com.klg.jclass.chart3d.Chart3dGridDataModel source, com.klg.jclass.chart3d.Chart3dGridDataModel dest) Copies the xGrid, yGrid, and zValues of the source argument into the dest argument.
static double	estimateInitialSlopeOfCurve(double x0, double y0, double x1, double y1, double x2, double y2) Estimates the initial slope of the curve which contains the points (x0, y0), (x1, y1), (x2, y2).
static double	evaluateCubicSpline(double x, double a, double b, double c, double d) Evaluates the cubic spline defined by f(x) = a + bx + c^2 + dx^3 at the specified parameter x value and returns the result.
static double	evaluateLinearSpline(double x, double a, double b) Evaluates the linear spline defined by f(x) = a + bx at the specified parameter x and returns the result.
static int	findInsertionIndex(double value, double[] values) Returns the index whereby value would be inserted into the specified array values to maintain ascending order.
static int	findInsertionIndex(double value, double[] values, int n) This method is identical to findInsertionIndex(double, double[]), except that it restricts the valid range of values to [values[0], values[n-1]].
static double	getHoleValue(com.klg.jclass.chart3d.Chart3dDataModel model) A convenience method which returns the hole value for the specified Chart3dDataModel.
static int	getSizeX(com.klg.jclass.chart3d.Chart3dGridDataModel model) A convenience method which returns the size of the specified data model's x grid, or 0 if the model has no x data.
static int	getSizeY(com.klg.jclass.chart3d.Chart3dGridDataModel model) A convenience method which returns the size of the specified data model's y grid, or 0 if the model has no y data.

Methods inherited from class java.lang.Object

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

Field Detail

DATA_INTERPOLATE_LINEAR

public static final int DATA_INTERPOLATE_LINEAR

See Also:

Constant Field Values

DATA_INTERPOLATE_CUBIC

public static final int DATA_INTERPOLATE_CUBIC

See Also:

Constant Field Values

Constructor Detail

JCData3dUtil

public JCData3dUtil()

Method Detail

createDataCopy

public static com.klg.jclass.chart3d.Chart3dGridDataModel createDataCopy(com.klg.jclass.chart3d.Chart3dGridDataModel source)

Constructs a copy of the Chart3dGridDataModel source and returns it. Only the xGrid, yGrid, and zValues are copied.

Parameters:

source - the data model to copy

Returns:

a copy of the source xGrid, yGrid, and zValues

dataCopy

public static void dataCopy(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                            com.klg.jclass.chart3d.Chart3dGridDataModel dest)

Copies the xGrid, yGrid, and zValues of the source argument into the dest argument. The source and dest must be compatible for this method to work (in other words, the xGrid, yGrid, and zValues arrays of source and dest must be non-null and of equal size).

Parameters:

source -

dest -

createShadedDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createShadedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                double sweepAngle,
                                                                                double riseAngle,
                                                                                double brightness,
                                                                                double ambient)

Constructs an array of z values for the specified Chart3dGridDataModel source where each z value is a measurement of light on the closed range [0,1]. The amount of light at a given grid point has two components: ambient and reflected.

The ambient component is constant for all grid points, and is specified by the ambient argument (which must be on the range [0,1]).

The reflected component is the dot product of two vectors. The first is the light normal - a unit vector defined by the sweepAngle and riseAngle arguments. The sweepAngle is the position of the light source measured in degrees from the positive x axis in the xy plane. The riseAngle is the position of the light source measured in degrees above the xy plane. The second is the surface normal - a unit vector computed at each individual grid point.

The light at a given grid point is given by: light(x,y) = ambient + (1-ambient) * lightNormal·surfaceNormal(x,y)

The total amount of light at a given grid point is then adjusted for overall brightness by: lightAdjusted(x,y) = brightness * light(x,y) where brightness is on the closed range [0,1].

The source Chart3dGridDataModel is cloned, and the shaded values are then put into the array of z-values belogning to the clone. z-values belong to the Chart3dGridDataModel dest.

Parameters:

source - the non-null data model used to compute the shaded data

sweepAngle -

riseAngle -

brightness -

ambient -

Returns:

- Chart3dGridDataModel containing the same x and y grid as source, and z-values corresponding to the array of shaded values at each grid point

createShadedDataModel

public static void createShadedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                         com.klg.jclass.chart3d.Chart3dGridDataModel dest,
                                         double sweepAngle,
                                         double riseAngle,
                                         double brightness,
                                         double ambient)

Constructs an array of z values for the specified Chart3dGridDataModel source where each z value is a measurement of light on the closed range [0,1]. The amount of light at a given grid point has two components: ambient and reflected.

The ambient component is constant for all grid points, and is specified by the ambient argument (which must be on the range [0,1]).

The reflected component is the dot product of two vectors. The first is the light normal - a unit vector defined by the sweepAngle and riseAngle arguments. The sweepAngle is the position of the light source measured in degrees from the positive x axis in the xy plane. The riseAngle is the position of the light source measured in degrees above the xy plane. The second is the surface normal - a unit vector computed at each individual grid point.

The light at a given grid point is given by: light(x,y) = ambient + (1-ambient) * lightNormal·surfaceNormal(x,y)

The total amount of light at a given grid point is then adjusted for overall brightness by: lightAdjusted(x,y) = brightness * light(x,y) where brightness is on the closed range [0,1].

The resultant light for each grid point is then stored in the array of z-values belogning to the Chart3dGridDataModel dest.

Parameters:

source - the non-null data model used to compute the shaded data

dest - the non-null data model used to store the resultant shaded data

sweepAngle -

riseAngle -

brightness -

ambient -

createSmoothedDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createSmoothedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                  double centreWeight)

Constructs a data model with a data surface with the same x and y grid values of source, but with "smoothed" z values.

The smoothing algorithm is a centre weighted average algorithm which functions as follows:
Each smoothed z value is a combination of itself, as well as a contribution from all immediate neighbouring z values (values to the West, Northwest, North, NorthWest, and so on). The contribution that the candidate itself makes is proportional to the centreWeight argument, which can be anywhere from 0.0 (no contribution) to 1.0 (100% contribution). Any remaining contribution is divided amongst all other contributors and is inversely proportional to the distance from the each neighbour to the candidate.
Note: Any data holes will remain data holes, and will not contribuite to the smoothed values of its neighbours.

The source data model is not affected by this method.

Parameters:

source - the data model used to construct the smoothed values

centreWeight -

Returns:

a data model with the same xGrid and yGrid as source, but with the resultant "smoothed" zValues in its zValues array

Throws:

IllegalArgumentException - if there are fewer than 2x2 data values

createSmoothedDataModel

public static void createSmoothedDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                           com.klg.jclass.chart3d.Chart3dGridDataModel dest,
                                           double centreWeight)

Constructs a data model with a data surface with the same x and y grid values of source, but with "smoothed" z values.

The smoothing algorithm is a centre weighted average algorithm which functions as follows:

Each smoothed z value is a combination of itself, as well as a contribution from all immediate neighbouring z values (values to the West, Northwest, North, NorthWest, and so on). The contribution that the candidate itself makes is proportional to the centreWeight argument which can be anywhere from 0.0 (no contribution) to 1.0 (100% contribution). Any remaining contribution is divided amongst all other contributors and is inversely proportional to the distance from the each neighbour to the candidate.
Note: Any data holes will remain data holes, and will not contribuite to the smoothed values of its neighbours.

The source data model is not affected by this method.

Parameters:

source - the data model used to construct the smoothed values

dest - the data model used to store the smoothed values

centreWeight -

Throws:

IllegalArgumentException - An IllegalArgumentException if there are fewer than 2x2 data values.

computeInverseWeightedAverage

public static double computeInverseWeightedAverage(double[] values,
                                                   double[] weights,
                                                   double centreWeight,
                                                   int centreIndex,
                                                   double holeValue)

Generates a weighted average value for a data point based on its own value, as well as contributions from values contained in the values array. The contribution each value makes is based upon the formula:
(weightSum - value[i]) contribution[i] = ---------------------- X (1 - centreWeight) weightSum
except contribution[centreIndex], which is:
contribution[centreIndex] = value[centreIndex] X centreWeight

weightedSum is the sum of all weights except for weights[centreIndex]. The weighted average is essentially just the sum of every contribution. If hasHoles is true, all values which are equal to holeValue will be ignored and will not impact the weighted average computation.

Parameters:

values -

weights -

centreWeight -

centreIndex -

holeValue -

Returns:

findInsertionIndex

public static int findInsertionIndex(double value,
                                     double[] values)

Returns the index whereby value would be inserted into the specified array values to maintain ascending order. The array of values must be in ascending order for this method to function properly.

For example, if value is 2.8 and values is [0.0, 2.5, 3.1, 4.5], then 2 is returned. Note the following boundary conditions for the above values: if value is 0.0, 1 is returned; if value is 4.5, 3 is returned.

Parameters:

value -

values -

Returns:

index at which value is inserted into the array values to maintain ascending order, or -1 if value is less than values[0] or greater than values[length-1]

findInsertionIndex

public static int findInsertionIndex(double value,
                                     double[] values,
                                     int n)

This method is identical to findInsertionIndex(double, double[]), except that it restricts the valid range of values to [values[0], values[n-1]].

Parameters:

value -

values -

n -

Returns:

createLinearSplineCoefficients

public static void createLinearSplineCoefficients(double[] x,
                                                  double[] y,
                                                  double[] a,
                                                  double[] b,
                                                  int n)

Fits a piecewise linear spline to the series of x,y points. Each cubic spline is represented by:
f (u) = a[index] + b[index]u index
where index is defined on the range [0, n-1], and u is defined on the range [0, x[index+1] - x[index]].

The a and b coefficients are placed into the a and b arrays, respectively.

Parameters:

x -

y -

a -

b -

n -

createCubicSplineCoefficients

public static void createCubicSplineCoefficients(double[] x,
                                                 double[] y,
                                                 double[] a,
                                                 double[] b,
                                                 double[] c,
                                                 double[] d,
                                                 int n)

Fits a piecewise cubic spline to the series of x,y points. Each cubic spline is represented by:
f (u) = a[index] + b[index]u + c[index]u^2 + d[index]u^3 index
where index is defined on the range [0, n-1], and u is defined on the range [0, x[index+1] - x[index]]. The slope at the beginning of the series and at the end of the series is estimated using qadratic interpolation. The curve fitting algorithm used is outlined in Conte and deBoor, Elementary Numerical Analysis, An Algorithmic Approach, 3rd edition, pp 284-292.

Parameters:

x -

y -

a -

b -

c -

d -

n - the number of intervals on which to generate spline coefficients

evaluateCubicSpline

public static double evaluateCubicSpline(double x,
                                         double a,
                                         double b,
                                         double c,
                                         double d)

Evaluates the cubic spline defined by f(x) = a + bx + c^2 + dx^3 at the specified parameter x value and returns the result. The x parameter must be on the range of the spline for the result to be valid.

Parameters:

x -

a -

b -

c -

d -

Returns:

the initial slope of a quadratic curve fitted to the points (x0,y0), (x1,y1), and (x2,y2)

evaluateLinearSpline

public static double evaluateLinearSpline(double x,
                                          double a,
                                          double b)

Evaluates the linear spline defined by f(x) = a + bx at the specified parameter x and returns the result. The x parameter must be on the range of the spline for the result to be valid.

Parameters:

x -

a -

b -

Returns:

estimateInitialSlopeOfCurve

public static double estimateInitialSlopeOfCurve(double x0,
                                                 double y0,
                                                 double x1,
                                                 double y1,
                                                 double x2,
                                                 double y2)

Estimates the initial slope of the curve which contains the points (x0, y0), (x1, y1), (x2, y2). The slope is estimated by fitting a quadratic curve to the specified points, then computing the first derviative at point (x0, y0). The x values of the points must be in ascending or descending order for this method to function properly.

Parameters:

x0 -

y0 -

x1 -

y1 -

x2 -

y2 -

Returns:

the initial slope of a quadratic curve fitted to the points (x0,y0), (x1,y1), and (x2,y2)

createLinearSampledDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createLinearSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                       RectangularShape dataWindow,
                                                                                       int xSampleSize,
                                                                                       int ySampleSize)

Constructs a data model by taking xSampleSize and ySampleSize samples along the x and y axes of the source. The first x sample is taken along the source x axis at dataWindow.getMinX(), and the last at dataWindow.getMaxX(). The first y sample is taken along the source y axis at dataWindow.getMinY(), and the last at dataWindow.getMaxY(). All samples are equally spaced between the first and last samples along each axis respectively.

The zValues at each sample location are computed by interpolation of a series of piecewise linear splines which are fitted to the data values in both the x and y directions.

Parameters:

source -

dataWindow -

xSampleSize -

ySampleSize -

Returns:

a Chart3dGridDataModel, or null (if source is null)

Throws:

NullPointerException - If any of source or dataWindow is null.

IllegalArgumentException - If the source data model contains fewer than a 2x2 grid of data values, or if xSampleSize or ySampleSize is less than 2.

createLinearSampledDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createLinearSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                       double[] xSamples,
                                                                                       double[] ySamples)

Constructs a data model by taking xSamples.length and ySamples.length samples along the x and y axes of the source. The samples of the source data will be taken at locations defined by a grid formed by the xSamples and ySamples arrays. To function properly, both of these arrays should be in ascending order.

The Values at each sample location are computed by interpolation of a series of piecewise linear splines which are fitted to the data values in both the x and y directions.

Parameters:

source -

xSamples -

ySamples -

Returns:

- a Chart3dGridDataModel, or null (if source is null)

Throws:

NullPointerException - If any of source, xSamples, or ySamples is null.

IllegalArgumentException - If the source data model contains fewer than a 2x2 grid of data values, or if xSamples or ySamples contains fewer than 2 samples.

createCubicSampledDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createCubicSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                      double[] xSamples,
                                                                                      double[] ySamples)

Constructs a data model by taking xSamples.length and ySamples.length samples along the x and y axes of the source. The samples of the source data will be taken at locations defined by a grid formed by the xSamples and ySamples arrays. To function properly, both of these arrays should be in ascending order.

The zValues at each sample location are computed by interpolation of a series of piecewise cubic splines which are fitted to the data values in both the x and y directions. The cubic interpolation generally results in a more authentic approximation to the data than a linear interpolation.
Note: If there are fewer than 3 available data values along a given axis, linear interpolation will be used by default.

Parameters:

source -

xSamples -

ySamples -

Returns:

a Chart3dGridDataModel, or null (if source is null)

Throws:

NullPointerException - If any of source, xSamples, or ySamples is null.

IllegalArgumentException - If the source data model contains fewer than a 2x2 grid of data values, or if xSamples or ySamples contains fewer than 2 samples.

createCubicSampledDataModel

public static com.klg.jclass.chart3d.Chart3dGridDataModel createCubicSampledDataModel(com.klg.jclass.chart3d.Chart3dGridDataModel source,
                                                                                      RectangularShape dataWindow,
                                                                                      int xSampleSize,
                                                                                      int ySampleSize)

Constructs a data model by taking xSampleSize and ySampleSize samples along the x and y axes of the source. The first x sample is taken along the source x axis at dataWindow.getMinX(), and the last at dataWindow.getMaxX(). The first y sample is taken along the source y axis at dataWindow.getMinY(), and the last at dataWindow.getMaxY(). All samples are equally spaced between the first and last samples along each axis respectively.

The zValues at each sample location are computed by interpolation of a series of piecewise cubic splines which are fitted to the data values in both the x and y directions. The cubic interpolation generally results in a more authentic approximation to the data than a linear interpolation. Note however that if there are fewer than 3 available data values along a given axis, linear interpolation will be used by default.

Parameters:

source -

dataWindow -

xSampleSize -

ySampleSize -

Returns:

a Chart3dGridDataModel, or null (if source is null)

Throws:

NullPointerException - If any of source or dataWindow is null.

IllegalArgumentException - If the source data model contains fewer than a 2x2 grid of data values, or if xSampleSize or ySampleSize is less than 2.

getHoleValue

public static double getHoleValue(com.klg.jclass.chart3d.Chart3dDataModel model)

A convenience method which returns the hole value for the specified Chart3dDataModel. If the model implements the HoleValue3dDataModel interface, returns HoleValue3dDataModel.getHoleValue(); otherwise, returns HoleValue3dDataModel.DEFAULT_HOLE_VALUE.

Parameters:

model -

Returns:

getSizeX

public static int getSizeX(com.klg.jclass.chart3d.Chart3dGridDataModel model)

A convenience method which returns the size of the specified data model's x grid, or 0 if the model has no x data.

Parameters:

model -

Returns:

the size of the of the data model argument's x grid, or 0 if the data model has no x grid

getSizeY

public static int getSizeY(com.klg.jclass.chart3d.Chart3dGridDataModel model)

A convenience method which returns the size of the specified data model's y grid, or 0 if the model has no y data.

Parameters:

model -

Returns:

the size of the of the data model argument's y grid, or 0 if the data model has no y grid