You will find information on the following topics:

Overview of the Coordinate Transformations

As soon as you work with different coordinate systems and datums, you need to be able to convert from one to another. When working with coordinate systems, this can be performed using functions.

In addition to that, all the coordinate transformations implement the following methods:

The following sections describe the predefined built in transformations of JViews Maps, and provide some examples of the transformation package.

Transformation Paths

The chaining of elementary transformations from one coordinate system to another is called a transformation path.

Example

Convert from the following projected coordinate system:

to the following one:

The transformation path selected by CreateTransformation() will be:

Note that this path is not the only existing path. It is also possible to convert from geographic coordinates to geocentric coordinates, in which case the transformation path would be:

Predefined Math Transformations

In this section you will find information on the following topics:

Abridged Molodensky Transform

The standard way to convert coordinates from one datum to another is to convert first the coordinates to geocentric coordinates, apply the datum shift and rotation parameters, and then convert them back to geographic coordinates.

As an alternative to this transform, the IlvAbridgedMoldenskyTransform class implements directly a transform derived directly from the Moldenski formulas. The Abridged form of these formulas are quite satisfactory for three-parameter transformations.

This transform can work on either 2-D (only latitude and longitude are modified), or 3-D (the ellipsoidal height of coordinates is also modified).

Affine Transform

Affine transforms are commonly used in coordinate transformation. An affine transform is simply defined by a 4x4 double values matrix, and are applied to coordinates by multiplying them as if they were one 1x4 matrix.

Affine transforms are mainly used in JViews Maps for unit conversions in a transformation path.

Another use of affine transforms is to use them to implement Bursa Wolf transformations. The Bursa Wolf transformation is applied to geocentric coordinates to model a seven-parameter datum change. A seven-parameter datum is defined by the dX, dY, dZ axis shifts, the eX, eY, eZ rotations around the axis, and a scale factor expressed in parts per million. The matrix to use for Bursa Wolf transformation is:

Concatenated Transform

Geocentric Transform

Projection Transform

Transforming Data

This section helps you get started with coordinate transformations and coordinate systems. It is based on a simple example that illustrates the basic operations required to define the coordinate systems, and shows how to use the coordinate transformations back and forth.

This example is composed of the following steps:

The complete source code of the example on which this section is based can be found in the following file:

Example Overview

The Sample1.java file contains a very simple program that shows how to convert coordinates from geographic coordinates to a projected coordinate system, using a Mercator projection.

This class has only a static main() method, in which the coordinate systems are instantiated and the coordinate is transformed.

Choosing a Source and a Destination Coordinate System

As our example uses coordinate systems and transformation, the relevant packages must be imported, as well as the projection package for the Mercator projection definition:

import ilog.views.maps.*;
import ilog.views.maps.srs.coordsys.*;
import ilog.views.maps.srs.coordtrans.*;
import ilog.views.maps.projection.*;

The first important step is to define the source and the target coordinate systems.

For the source coordinate system, some latitude and longitude coordinates expressed in degrees are needed. This is the kind of coordinate defined in a geographic coordinate system. In this example, the WGS84 coordinate is used. The WGS84 geographic coordinate system defines ellipsoidal coordinates over the standard WGS84 ellipsoid.

IlvCoordinateSystem sourceCS = IlvGeographicCoordinateSystem.WGS84;

Now these coordinates must be changed to Mercator coordinates. Then you can create a new projected coordinate system using the Mercator projection to express coordinates. Note that the Mercator projection should use exactly the same geodetic parameters as the WGS84 geographic coordinate system. The latter is passed as the geographic coordinate system of the projected coordinate system.

IlvCoordinateSystem targetCS = 
   new IlvProjectedCoordinateSystem("Mercator",
                                    IlvGeographicCoordinateSystem.WGS84,
                             new IlvMercatorProjection(),
                             IlvLinearUnit.METER,
                             "X",   // The X axis name
                             "Y");  // The Y axis name

Transforming Coordinates

The transform() method takes two parameters: the first one is the source coordinate to transform, the second one is an IlvCoordinate to hold the result of the transformation. When this second parameter is null, a new IlvCoordinate is allocated and used. The method returns the result coordinate.

Of course, as in this example, it is possible to use the same IlvCoordinate as source and destination.

Note that the IlvCoordinateTransformation.transform() method may throw different kinds of exception if the transformation process leads to mathematical errors or overflows. Most of the time, when those methods are thrown, the transformation is not defined at the specified point.

Displaying the Result

The result of the transformation is now stored in the coord variable. In the following code example, the result is expressed in meters, which is the default measurement unit.

System.out.println("The Mercator coordinates of 45W 30N is ");
System.out.println("x = " + (int) coord.x + " m");
System.out.println("y = " + (int) coord.y + " m");

Getting the Inverse Transformation

At this point, the methodology to convert from geographic coordinates to Mercator coordinates is available.

Printing Geographic Coordinates

For example, IlvAngularUnit.DEGREE.toDMS() converts an angle specified in degrees to DMS.

System.out.println("The inverse projection is " 
                + IlvAngularUnit.DEGREE.toDMS(coord.x,false) 
                + " "
                + IlvAngularUnit.DEGREE.toDMS(coord.y,true));

Adding Graphic Objects on Top of an Imported Map

This section shows how to import an .ivl map file whose coordinate system is known into a JViews Maps manager, and how to lay graphic objects over that map. It is based on an example that loads a map of the USA projected with a Lambert Azimuthal Equal Area projection into a manager, and adds cities on top of the map. The geographic coordinates indicated by the mouse pointer as well as the name of the cities pointed to are displayed in text fields at the bottom of the window. This section also gives information about the instantiating and the parameterization of a projected coordinate system, describes how to convert data from geographic coordinates to this projected coordinate system, and how to use a view interactor.

The example is composed of the following steps:

The complete source code for this example can be found in the following file:

Initializing Coordinate Systems

Since you need to convert from geographic coordinates to projected coordinates and vice versa, you need to keep an instance of these transformations. This is performed by means of the createTransformations() method.

First, initialize an instance of the projection used in the coordinate system of the imported map. In this example, the usa.ivl file is in Lambert Azimuthal Equal Area projection.

The projection parameters are:

Note that projection parameters are always specified using kernel units. In this case, the central meridian and parallel have to be specified in radians. Use the method IlvAngularUnit.RADIAN.fromDMS() to achieve this goal.

Once the Lambert Azimuthal projection has been initialized, you only have to create the corresponding projected coordinate system:

// Create the projected coordinate system.
IlvProjectedCoordinateSystem projectedCS = 
  new IlvProjectedCoordinateSystem("Lambert Azimutal Equal Area",
                                 projection);

You also create a geographic coordinate system whose ellipsoid is a simple sphere:

// Create the geographic coordinate system.
IlvGeographicCoordinateSystem geoCS =
   new IlvGeographicCoordinateSystem(IlvHorizontalShiftDatum.SPHERE_WGS84,
                             IlvMeridian.GREENWICH);

Finally, create the coordinate transformation and store also the inverse transformation for future quick reference:

// A coordinate transform.
geo2projCT = 
 IlvCoordinateTransformation.CreateTransformation(geoCS,projectedCS);
// The inverse transform.
proj2geoCT = geo2projCT.getInverse();

Adding Cities

The addCitites() method adds a number of cities on top of the imported map of the United States:

private void addCities()
{
  addCity("Washington", "39D11'N", "76D51W");
  addCity("New York", "40D59'N", "73D39'W");
  addCity("Miami", "25D58'N", "80D02'W");
  addCity("San Francisco", "37D44'N", "122D20'W");
  addCity("Seattle", "47D51'N", "122D01'W");
  addCity("Denvers", "39D50'N", "104D53'W");
}

The coordinate conversion is performed in the addCity() method.

First, this method converts the DMS coordinates specified as string to degrees, in order to have the longitude and latitude coordinates of each point:

private void addCity(String cityName, String lat, String lon)
{
  try {
    double latitude = IlvAngularUnit.DEGREE.fromDMS(lat);
    double longitude = IlvAngularUnit.DEGREE.fromDMS(lon);
    IlvCoordinate coordinate = new IlvCoordinate(longitude,
                                                 latitude);

Then, it computes the projected coordinates by applying the forward coordinate transformation. If the coordinates cannot be transformed (for example, because the tolerance conditions have been exceeded), the transformation may throw an exception. This is why the code is contained inside a try/catch block.

The IlvProjectionUtil.invertY() method is then called to invert the y-coordinate: in the JViews Maps manager coordinate system, the y-axis is oriented downwards, whereas, in the projection coordinate system, it is oriented upwards.

    geo2projCT.transform(coordinate,coordinate);
    IlvPoint p = new IlvPoint((float)coordinate.x,
                                (float)coordinate.y);
    IlvProjectionUtil.invertY(p);

Note also that a new IlvPoint is allocated here. It will be used to create graphic objects (an IlvMarker) to represent the city. This graphic object is added to Layer #1 of the manager (Layer #0 contains the boundaries of the USA).

  IlvMarker marker = new IlvMarker(p, IlvMarker.IlvMarkerFilledDiamond);
      marker.setSize(4);
      marker.setForeground(Color.red);
      manager.addObject(marker, 1, false);
      marker.setName(cityName);
  } catch (IlvCoordinateTransformationException e) {
      e.printStackTrace();
  }

Setting the View Interactor

In order to track mouse position, a view interactor is used. This is performed by means of the setViewInteractor() method.

First, create a selection interactor that will be used to select cities on the map. This interactor is configured so that multiple selections are not allowed, and the map cannot be modified, which means that the user will not be able to move cities around the map. The interactor is associated with the view. Note also that the elements making up Layer #0 (that is, borders) cannot be selected either.

private void setViewInteractor()
{
  IlvSelectInteractor interactor = new IlvSelectInteractor();
  interactor.setDragAllowed(false);
  interactor.setEditionAllowed(false);
  interactor.setMoveAllowed(false);
  interactor.setMultipleSelectionMode(false);
  manager.setSelectable(0, false);
  mgrview.pushInteractor(interactor);

Then, add a listener to the interactor that will display the longitude and the latitude indicated by the mouse in the appropriate text field. To compute the latitude and the longitude, apply the inverse transformation computed previously. The result returned by this method is formatted with the IlvAngularUnit.DEGREE.toDMS() method.

  // Display the position of the mouse.
  interactor.addMouseMotionListener(new MouseMotionAdapter() {
    public void mouseMoved(MouseEvent e) {
      // Get the point in manager coordinates.
      IlvTransformer t = mgrview.getTransformer();
      IlvPoint p = new IlvPoint(e.getX(), e.getY());
      t.inverse(p);
      IlvProjectionUtil.invertY(p);
      // Display the mouse position.
      try {
        IlvCoordinate c = new IlvCoordinate(p.x,p.y);
        proj2geoCT.transform(c,c);
        llField.setText(IlvAngularUnit.DEGREE.toDMS(c.x,false)
                        + " " +
                       IlvAngularUnit.DEGREE.toDMS(c.x,true));
      } catch (IlvCoordinateTransformationException ex) {
         System.out.println("Unable to inverse this point " + 
                            ex.getMessage());
       }
    }
  });

Finally, add a listener to the manager. This listener will display the name of the selected city in the appropriate text field.

manager.addManagerSelectionListener(new ManagerSelectionListener(){
  public void selectionChanged(ManagerSelectionChangedEvent e) {
    IlvGraphic g = e.getGraphic();
    if (g == null)
      return;
    String name = g.getName();
    if (name != null) 
       cityField.setText(name);
    }
  });