sugr
Class Element

java.lang.Object
  extended bysugr.Element
All Implemented Interfaces:
java.lang.Cloneable, java.io.Serializable
Direct Known Subclasses:
Entity, Transformation

public abstract class Element
extends java.lang.Object
implements java.lang.Cloneable, java.io.Serializable

This class is the "mother" of all elements like like Point_2D, Line_3D, Plane_3D, Transformation and so on. It's abstract and it is a place where non specific method may be placed This class knowns nothing about a homogenous and euclidean part. This distinction is done in the subclass Entity.

Version:
1.1 (25.1.2004) Added calcCov() as protected method to this class, because it is used in some Constructors of Lines and Points.
Author:
Norbert Fischer
See Also:
Serialized Form

Field Summary
private static double CHANGETHRESHOLD
          Factor between unknown and its accuracy for stopping iteration
private static double CONSTRAINTZEROTHRESHOLD
          Function ensureConstraints: Threshold for the constraint value to be zero.
protected  Matrix cov
          Represents the Covariance Matrix
private static double EPSILON
          Variance in direction of Nullspace.
protected static int MAXITER
          Default maximal number of iterations for Gauss-Helmert iteration
private static int MAXITER2
          Maximal number of iterations for applying constraints
protected  Vector v
          Represents the coordinates of an Entitiy like Point_3D.
 
Constructor Summary
Element()
           
 
Method Summary
 void approximate(RelationalProperty[] rprops)
          Compute an approximation of an entity.
protected static Matrix calcCov(Matrix U_x, Matrix Sigma_x, Matrix V_y, Matrix Sigma_y)
          starts the error propagation of the uncertainty elements
 void changeNullspace()
          The covariance matrix is changed in that way: An orthogonal projection onto {y}^{orthogonal} will be done.
 void changeNullspace(double epsilon)
          The covariance matrix is changed in that way: An orthogonal projection onto {y}^{orthogonal} will be done.
 void checkCovDim(Matrix cov, int dim)
          Checks the dimension of a given covariance matrix if it matches the dimension of the element
static void checkElement(Vector vec, int dim)
          Checks if not all values are = 0.
 java.lang.Object clone()
          Clone an element.
abstract  void doCondition(double[] f)
          Condition that element with a set of conditioning factors.
 void ensureConstraints()
          Change the entity (covariance not changed) in that way, that all constraints (given by getConstraintValue) are fulfilled.
 boolean estimate(RelationalProperty[] rprops)
          Estimation of that entity out of given relational properties.
 boolean estimate(RelationalProperty[] rprops, boolean doConditioning, int maxiter, RelationalProperty[] yhat, double[] sigma0, int[] no_of_iterations, boolean estimate_sigma0)
          Estimation of that entity out of given relational properties.
 boolean gaussHelmertIterations(RelationalProperty[] rprops, int maxiter, RelationalProperty[] yhat, double[] sigma0, int[] no_of_iterations, boolean estimate_sigma0)
           
 boolean gaussHelmertIterationsOld(RelationalProperty[] rprops, int maxiter, RelationalProperty[] yhaterg, double[] sigma0, int[] no_of_iterations, boolean estimate_sigma0)
          Iterations of a Gauss-Helmert model for estimating new entities.
protected  Vector getConstraintValue()
          Get the value of the constraint (h(beta) or g(y)) if this entity is an unknown or an observation.
 Matrix getCov()
          returns the Covariance Matrix.
abstract  int getDegreesOfFreedom()
          returns the minimum number of parameters to construct an element
abstract  int getDimension()
          returns the dimension of an element.
 Matrix getJacobianOfConstraint()
          Get the Jacobian of the constraint (H, G) if this entity is an unkown or an observation.
abstract  Matrix getJacobianOfRelation(RelationalProperty r)
          Return Jacobian Matrix in combination with a relation.
protected  Matrix[] getReducedAB(RelationalProperty r)
          Get the reduced Matrix A and B from a relational property.
 Vector getV()
          returns coordinates of the element in a Vector BE CAREFUL: You get the reference of the vector, so a change of the reference results in a change of the Element !
 void normalizeSphere()
          Normalize this element to unit-vector length
 void normalizeSphereComparable()
          Sherical normalization with comparable result: To avoid a sign ambiguity the largest element |xi| of v is positive after this normalization.
 void print()
          prints this element to stdout.
 void print(int width, int digits)
          prints this element to stdout.
static Matrix[] reduceFirstMatrix(Matrix A, Matrix B, int dof)
          Reduce two Jacobian matrixes consistently based on solely the first matrix A.
static Matrix reduceMatrix(Matrix A, int dof)
          Reduce a Jacobian matrix.
static Matrix[] reduceMatrix(Matrix A, Matrix B, int dof)
          Reduce two Jacobian matrixes consistently.
 void setCov(Matrix C)
          Sets the covariance matrix of this element.
 void setV(Vector v)
          Sets the coordinates of the element BE CAREFUL: The reference is set, so no copy is made !
 java.lang.String toString()
          Print out element.
 
Methods inherited from class java.lang.Object
equals, finalize, getClass, hashCode, notify, notifyAll, wait, wait, wait
 

Field Detail

cov

protected Matrix cov
Represents the Covariance Matrix


v

protected Vector v
Represents the coordinates of an Entitiy like Point_3D. It is also used to store a transformation from Transformation-classes.


MAXITER

protected static final int MAXITER
Default maximal number of iterations for Gauss-Helmert iteration

See Also:
Constant Field Values

CHANGETHRESHOLD

private static final double CHANGETHRESHOLD
Factor between unknown and its accuracy for stopping iteration

See Also:
Constant Field Values

EPSILON

private static final double EPSILON
Variance in direction of Nullspace. This only depends on the curvature of the space in the estimation.

See Also:
Constant Field Values

MAXITER2

private static final int MAXITER2
Maximal number of iterations for applying constraints

See Also:
Constant Field Values

CONSTRAINTZEROTHRESHOLD

private static final double CONSTRAINTZEROTHRESHOLD
Function ensureConstraints: Threshold for the constraint value to be zero. The iteration is stopped if this threshold has been reached.

See Also:
Constant Field Values
Constructor Detail

Element

public Element()
Method Detail

getCov

public Matrix getCov()
returns the Covariance Matrix. BE CAREFUL: You get the reference of the covariance matrix, so a change of the reference results in a change of the Element ! It may be insecure in future versions to modify the matrix without a final setV().

Returns:
a Matrix, containing the covariances

setCov

public void setCov(Matrix C)
Sets the covariance matrix of this element. BE CAREFUL: The reference is set, so no copy is made !

Parameters:
C - containing a suitable matrix

getV

public Vector getV()
returns coordinates of the element in a Vector BE CAREFUL: You get the reference of the vector, so a change of the reference results in a change of the Element ! It may be insecure in future versions to modify the vector without a final setV().

Returns:
a Vector

setV

public void setV(Vector v)
Sets the coordinates of the element BE CAREFUL: The reference is set, so no copy is made !

Parameters:
v - contains the coordinates

getDegreesOfFreedom

public abstract int getDegreesOfFreedom()
returns the minimum number of parameters to construct an element

Returns:
a int

getDimension

public abstract int getDimension()
returns the dimension of an element. E.g. Line_3D.getDimension() returns 6. For Transformations this is the dimension of the transformation matrix.


doCondition

public abstract void doCondition(double[] f)
Condition that element with a set of conditioning factors.

Parameters:
f - conditioning factors.

toString

public java.lang.String toString()
Print out element. If you want to have a better control of the output, use print(width, digits)

Returns:
a String with element vector and covariance.

normalizeSphere

public void normalizeSphere()
Normalize this element to unit-vector length


normalizeSphereComparable

public void normalizeSphereComparable()
Sherical normalization with comparable result: To avoid a sign ambiguity the largest element |xi| of v is positive after this normalization. This is slightly more expensive than normalizeShere


changeNullspace

public void changeNullspace()
The covariance matrix is changed in that way: An orthogonal projection onto {y}^{orthogonal} will be done. Vector ist not changed


changeNullspace

public void changeNullspace(double epsilon)
The covariance matrix is changed in that way: An orthogonal projection onto {y}^{orthogonal} will be done. Afterwards a small extension epsilon is added to the nullspace, so that the covariance matrix has full rank. Vector ist not changed.

Parameters:
epsilon - amount, that is added to the null-direction

print

public void print(int width,
                  int digits)
prints this element to stdout.
A common value is w=5, d=3

Parameters:
width - describes the space a value has to show itself
digits - how many places after the comma should be shown. it is not clever to choose digits >= width

print

public void print()
prints this element to stdout.


checkCovDim

public void checkCovDim(Matrix cov,
                        int dim)
Checks the dimension of a given covariance matrix if it matches the dimension of the element

Parameters:
cov - the covariance matrix to be checked
dim - the dimension of the element

checkElement

public static void checkElement(Vector vec,
                                int dim)
Checks if not all values are = 0. If so => error!

Parameters:
vec - the coordinates to be checked
dim - the dimension of the element

clone

public java.lang.Object clone()
Clone an element. The vector v and matrix c are cloned.

Returns:
a copy of the element.

approximate

public void approximate(RelationalProperty[] rprops)
Compute an approximation of an entity. The result of this method approximates the optimal solution which fullfills all the given relational constraints in an optimal way. The old values of the entity are overwritten. Implementation according to Table 3.12 on page 89 from dissertation from S. Heuel. No statistics are used, so the covariance matrix are set to 0. No conditioning is done !

Parameters:
rprops - a set of relational Properties which should be fullfilled.

estimate

public boolean estimate(RelationalProperty[] rprops)
Estimation of that entity out of given relational properties. To get Information about the estimation, call estimate with more parameters.

Parameters:
rprops - the observations

estimate

public boolean estimate(RelationalProperty[] rprops,
                        boolean doConditioning,
                        int maxiter,
                        RelationalProperty[] yhat,
                        double[] sigma0,
                        int[] no_of_iterations,
                        boolean estimate_sigma0)
Estimation of that entity out of given relational properties. Hints: Change your coordinate system in that way, that the entities lie around the origin. ! This seems important especially for 3D. Tests have shown sensitivity to such a transformation if estimating 3D points from 3D points and 3D lines from 3D lines. If distance between center of gravity and origin exceeds 1 conditioning is needed! If distance exceeds 10*10^14 conditioning can't help, you have to change coordinate system! See also: sugr.test.EstimationTest.conditioningTest() and its comments.

Parameters:
rprops - the observations
doConditioning - if true, a conditioning is done.
maxiter - maximum number of iterations.
yhat - corrected observations, spherically normalized. yhat=y-ehat.
sigma0 - sigma0 of the last iterations (sqrt(sigma2)) as an output parameter (array with 1 element)
no_of_iterations - number of iterations computed (output parameter: array with 1 element)
Returns:
true if convergence reached otherwise false. Convergence is not reached if the maximum number of iterations is reached and the convergence criteria is not reached.

gaussHelmertIterations

public boolean gaussHelmertIterations(RelationalProperty[] rprops,
                                      int maxiter,
                                      RelationalProperty[] yhat,
                                      double[] sigma0,
                                      int[] no_of_iterations,
                                      boolean estimate_sigma0)

gaussHelmertIterationsOld

public boolean gaussHelmertIterationsOld(RelationalProperty[] rprops,
                                         int maxiter,
                                         RelationalProperty[] yhaterg,
                                         double[] sigma0,
                                         int[] no_of_iterations,
                                         boolean estimate_sigma0)
Iterations of a Gauss-Helmert model for estimating new entities.

Parameters:
rprops - the (already conditioned) observations
maxiter - maximum number of iterations.
yhaterg - corrected observations, spherically normalized. yhat=y-ehat.
sigma0 - sigma0 of the last iterations (sqrt(sigma2)) as an output parameter (array with 1 element)
no_of_iterations - number of iterations computed (output parameter: array with 1 element)
Returns:
true if convergence reached otherwise false. Convergence is not reached if the maximum number of iterations is reached and the convergence criteria is not reached.

getConstraintValue

protected Vector getConstraintValue()
Get the value of the constraint (h(beta) or g(y)) if this entity is an unknown or an observation. This is the length constraint and for 3D-Lines also the plücker condition. Here is the default implementation for non 3D-Lines.

Returns:
the value of the constraint as a vector.

getReducedAB

protected Matrix[] getReducedAB(RelationalProperty r)
Get the reduced Matrix A and B from a relational property. A is the Jacobian of this Entity (the unknown), B is the Jacobian of the observation (the relational property). The Jacobian of the oberservation depends (only) on the unknown and the Jacobian of the unknown depends (only) of the oberservation ! This is the default implementation. It is overwritten for Transformations and is overwritten in Line_3D to handle the special case Equal(Line_3D, Line_3D) !

Parameters:
r - the relational Property
Returns:
A in array element 0, B in array Element 1.

reduceMatrix

public static Matrix reduceMatrix(Matrix A,
                                  int dof)
Reduce a Jacobian matrix. Only the rows with the largest norm are used for the reduced matrix.

Parameters:
A - the matrix to reduce
dof - the degrees of freedom=rank=number of rows of the reduced matrix.
Returns:
the reduced matrix.

reduceMatrix

public static Matrix[] reduceMatrix(Matrix A,
                                    Matrix B,
                                    int dof)
Reduce two Jacobian matrixes consistently. Only the rows with the largest norms |ui|*|vi| are used for the reduced matrix.

Parameters:
A - the first matrix to reduce
B - the second matrix to reduce
dof - the degrees of freedom=rank=number of rows of the reduced matrixes.
Returns:
the reduced matrixes. Element 0 = A, Element 1 = B

reduceFirstMatrix

public static Matrix[] reduceFirstMatrix(Matrix A,
                                         Matrix B,
                                         int dof)
Reduce two Jacobian matrixes consistently based on solely the first matrix A. Only the rows with the largest norms |ui| are used for the reduced matrix.

Parameters:
A - the matrix to reduce
dof - the degrees of freedom=rank=number of rows of the reduced matrixes.
Returns:
the reduced matrixes. Element 0 = A, Element 1 = B

getJacobianOfRelation

public abstract Matrix getJacobianOfRelation(RelationalProperty r)
Return Jacobian Matrix in combination with a relation. This is the Jacobian after the observations (given in the relational property). *this plays the role of the unknown.

Parameters:
r - a relational Property.
Returns:
Jacobian matrix (This is a part of the constraint formula)

getJacobianOfConstraint

public Matrix getJacobianOfConstraint()
Get the Jacobian of the constraint (H, G) if this entity is an unkown or an observation. This implementation is the Jacobian of the default constraint 0.5(v*vt-1)=0

Returns:
the Jacobian as a matrix.

calcCov

protected static Matrix calcCov(Matrix U_x,
                                Matrix Sigma_x,
                                Matrix V_y,
                                Matrix Sigma_y)
starts the error propagation of the uncertainty elements

Parameters:
U_x - The first jacobian between element 1 and 2
Sigma_x - the covariance matrix of element 1
V_y - the second jacobian between element 2 and 1
Sigma_y - the covariance matrix of element 2
Returns:
the calculated covariance matrix of the new element

ensureConstraints

public void ensureConstraints()
Change the entity (covariance not changed) in that way, that all constraints (given by getConstraintValue) are fulfilled. This is done by a Gauss-Helmert-Iterations without unknowns. Attention: A covariance matrix must be set ! TODO: Check why G*cov*Gt sometimes gets singular