Department of Photogrammetry, University of Bonn 

Tutorial 

This is the tutorial for the Javalibrary SUGR. 
Overview 

In this first steps you learn some basics about the javalibrary SUGR. 
Introduction  back to overview 
An entity is a line, point or a plane and in SUGR this entities are named like this:
SUGR uses the framework of homogeneous coordinates, thus 2dimensional entities are represented by 3dimensional vectors. This vectors consist of a homogeneous and an euclidean part. If the homogeneous part of a 2D point, as the third entry of the corresponding vector, has a value of "1", you have euclidean coordinates in the first two entries. 
Construction of certain 2DPoints and 2DLines  back to overview 
First you learn to construct points and lines in 2D in different ways.
At first you give the values, later you construct one entity with the help of two others.
Afterwards you will create an output for these entities. At first we construct a point in 2dimensional space.
If the homogeneous subvector, containing of the first two elements, is normalized to "1", it is the normal of the line and the euclidean part (third entry) is the euclidean distance to the origin.


Normalizations implemented in SUGR  back to overview 
If you are not familiar with homogeneous coordinates, you surely had problems with this output. To get a better understanding, you can normalize this point. If you use euclidean normalization, you get a vector with the normal euclidean point in the first two arguments and a "1" in the homogeneous part.
The spherical normalization divides the vector by it's length, normalizing it to a point on the corresponding standard sphere. The two "comparable" versions of the normalizations change the sign of the vector, if the biggest absolute value of all entries is negative. 

Construction of uncertain Entities  back to overview 
As the strength of SUGR is not to handle certain entities, but uncertain ones, this part is about uncertainty 2dimensional entities, their construction, some calculations and a statistical test. First we want to make some constructions very similar to those we saw before, but we include a covariance matrix to store uncertainties.
If you only have accuracies for the 2 coordinates of the 2Dpoint (and no covariances, that means that there are no correlations modeled), you can also simply use the constructor Point_2D(x,y, sigma_x, sigma_y). Next we construct a second point, which we use to construct a connecting line between the two points.
With the given euclidean coordinates of the two points (2,3) and (6,9) you can easily see, that the point (4,6) is on the connecting line, but with the given uncertainties, it is not that sure, that the point (4.001,6.0001) with the same uncertainties is NOT on the line. We need to do a statistical test.


Construct 3DEntities; 3DLine Introduction  back to overview 
3DPoints are represented very similar to the 2dimensional case. The first three entries of the corresponding vector are the euclidean part and the last entry is the homogeneous part. If the homogeneous part is normalized to the value of "1", the euclidean part is the 3vector in euclidean coordinates. The representation of 3DPlanes is similar to the representation of 2DLines. The first three components are the homogeneous part, and if this part is normalized to the value of "1", the last entry (the euclidean part of the plane) is the euclidean distance to the origin and the homogeneous part is the normal of the plane. In SUGR we use Plücker coordinates to represent 3Dlines. So the homogeneous and the euclidean part each consist of a tree dimensional vector. As not every 6vector is a line, the Plücker vector has to fulfill the Plücker constraint, which means that the crossproduct between the homogeneous and the euclidean part has to vanish. The best way to construct 3Dlines is to use other entities for construction, as a line is the join of two points, or the intersection of two planes. Use planes as input only in case you have generated them using either three points (this is a construction) or by fitting a plane through given entities using the GaußHelmertestimation procedure (see below). This is because it is difficult to generate realistic covariance matrices for planes manually.


GaussHelmertEstimation to construct an entity  back to overview 
There is another way for constructing entities in SUGR besides using a plain
constructor and using geometric reasoning. SUGR can estimate entities and even transformations for you, if redundancy is greater than zero. What do you need to do, to achive that? Well, let's say you have a bunch of points in 2D and want to lay a best fitting line through them. So you construct a line, using the standard constructor without parameters.
So let's take a look at the parameter "rprops". When you browse a little through the SUGR Api Documentation you will eventually find the RelationalProperties interface. There are two implementations: BiRelationalProperty and TriRelationalProperty. We will use BiRelationalProperty here, more exactly a subtype of it, because BiRelationalProperty is abstract. As you may guess, these subtypes of BiRelationalProperty stand for relations between two entities. There are four of these subtypes as mentioned before at Construction of uncertain Entities as relations, we can use for statistical tests. Be sure to take a closer look on them. Now, what do we need to do for our estimation problem? We define an array of Incident objects, each containing one of our points, and tell them, that the point should be incident to a Line_2D object:
If the iteration converged you have the best fitting line in your Line_2D object "bestFit" from above and can use it. Maybe you don't have points lying on a line, but are close together and you need to calculate the center of gravity? With SUGR, that's easy, too. As you may imagine we now use Equal instead of Incident. Let's change the example from above:
Experiment a little bit. Estimation in SUGR is quite easy to use and very usefull. Ah, not to forget, that you have to call the method estimate() on the centerOfGravity object again, just as before, but I think you got that. If you want to look at the uncertainties of the estimated object, just generate an output as learned before at Construction of certain 2DPoints and 2DLines. At last there is to mention, that you can mix relations by adding more observations with other subtypes of BiRelationalProperty before calling the method estimate() as done before. One hint: You may have a problem where more than one homogenoues entity should be estimated in a single adjustment step, because the unknown entities depend on each other due to the observations. SUGR is not able to estimate more than one entity simultaneously, but there's a Matlab package which can do that available here. Have fun with estimation! 

Transformations and ProjectiveCameras  back to overview 
Transformations, as they are used in SUGR, are line preserving mappings from 3D to 3D
or 2D to 2D. There is also a class modelling a projective camera which can be used to construct a line preserving mapping from 3D to 2D. In addition, it can be used for shooting a viewing ray into 3D, making 3Dlines from 2Dpoints. Transformations, in general, are represented as homogeneous transformation matrices. In SUGR this matrices are implemented as a columnvector with a corresponding covariance matrix as described before at Construction of uncertain Entities. From 3D to 3D, we have a vector with 16 entries, from 2D to 2D, it has 9 entries. A vector, representing a projective camera, has 12 entries, representing a 3x4 Matrix 3DTransformations are:
Well, now you're through with the tutorial. If you need further help, look at the SUGR Api Documentation. Have much fun using SUGR. 
