GeoCalc provides multiple methods for getting DatumShifts. If you know exactly what DatumShift you need, you can get it using the DataSource::GetDatumShift method as described above in Lesson 4, or you can get it using the ObjectPicker or DataSourcePicker as described in Lesson 5. Often, it is not known exactly which DatumShifts are needed, so the DataSourceComponent provides two methods to help you find the necessary DatumShifts. These methods are called EstablishDatumShift and GetValidDatumShifts. GeoCalc also provides a graphical way to find DatumShifts in the form of the DatumShiftPicker dialog. This dialog can be used to find all of the valid DatumShifts and select the best ones.
We will first need to create and load a DataSourceComponent, since this is what contains all of the DatumShift definitions we will want to select. For more information about using the DataSourceComponent, see Lesson 4.
Dim gcDataSource As New DataSourceComponent
gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml")
DataSourceComponent gcDataSource = new DataSourceComponent();
gcDataSource.LoadFile("c:\\bmg\\GeoCalcNET\\data\\geocalc.xml");
This method will allow you to specify some properties about the necessary DatumShifts, and then it will find some set of DatumShifts that satisfies these properties. This method requires two arguments: a CoordTransform object and a DatumShiftPreferences object. First, let's construct the CoordTransform. We will go into more depth about CoordTransforms in Lesson 7 and Lesson 8, but here we will just set the SourceCoordSys and TargetCoordSys properties, which indicate the input and output systems of the coordinate transformation.
Dim source As CoordSys = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E")
Dim target As CoordSys = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system")
Dim ct As New CoordTransform(source, target)
CoordSys source = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E");
CoordSys target = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system");
CoordTransform ct = new CoordTransform(source, target);
Here, we have constructed a CoordTransform that will convert coordinates from the US State Plane 27 Maine East system to the WGS84 geodetic system. Since these systems use different HorizontalDatums, we will need some DatumShifts in order to convert points. Before we use the EstablishDatumShift method to get a set of DatumShifts, we must create a DatumShiftPreferences object that describes some properties about the necessary DatumShifts. Suppose we want a set of DatumShifts that uses the Molodensky method, we don't care if the DatumShifts go through an intermediate HorizontalDatum, and we don't care about checking whether Envelopes match up. Then we would construct the DatumShiftPreferences object like this:
Dim prefs As New DatumShiftPreferences
prefs.Method = DatumShift.ClassType.Molodensky
prefs.Options = DatumShiftPreferences.ProcFlags.Direct Or DatumShiftPreferences.ProcFlags.ViaIntermediary Or DatumShiftPreferences.ProcFlags.IgnoreArea
DatumShiftPreferences prefs = new DatumShiftPreferences();
prefs.Method = DatumShift.ClassType.Molodensky;
prefs.Options = (int)(DatumShiftPreferences.ProcFlags.Direct | DatumShiftPreferences.ProcFlags.ViaIntermediary | DatumShiftPreferences.ProcFlags.IgnoreArea);
Now we are ready to get our DatumShifts with a call to the EstablishDatumShift method:
If Not gcDataSource.EstablishDatumShift(ct, prefs) Then
MessageBox.Show("EstablishDatumShift failed")
End If
if(! gcDataSource.EstablishDatumShift(ct, prefs))
{
MessageBox.Show("EstablishDatumShift failed");
}
If this method succeeds, then the CoordTransform::DatumShifts property will be populated with some DatumShifts that satisfy the properties described in the DatumShiftPreferences object and will shift from the SourceCoordSys to the TargetCoordSys of the CoordTransform.
This method will find all sets of DatumShifts that satisfy our requirements and then let us decide which set will work best. It requires four arguments, the first of which is the source CoordSys for the desired DatumShifts, the second of which is the target CoordSys for the DatumShifts, the third of which is a DatumShiftPreferencesEx object that describes the nature of the desired DatumShifts, and the fourth of which is a DatumShiftInfoSetCollection object that will hold information about the DatumShifts that fit our requirements. Let's start by constructing a CoordTransform in the same way we did above. Once again, we will go into more depth about the CoordTransform object in Lesson 7 and Lesson 8.
Dim source As CoordSys = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E")
Dim target As CoordSys = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system")
Dim ct As New CoordTransform(source, target)
CoordSys source = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E");
CoordSys target = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system");
CoordTransform ct = new CoordTransform(source, target);
Now we must construct a DatumShiftPreferencesEx object that describes the nature of the DatumShifts that we want. Let's suppose we are interested in DatumShifts that use either the Molodesky or Bursa-Wolfe method, and that we don't care if the DatumShifts use an intermediate HorizontalDatum, or if the Envelopes match. Then we would define our DatumShiftPreferencesEx like this:
Dim prefsEx As New DatumShiftPreferencesEx
prefsEx.BitFlags = DatumShiftPreferencesEx.BitFlag.Molodensky Or DatumShiftPreferencesEx.BitFlag.BursaWolfe
prefsEx.OnlyGoThruIntermediate = False
DatumShiftPreferencesEx prefsEx = new DatumShiftPreferencesEx();
prefsEx.BitFlags = DatumShiftPreferencesEx.BitFlag.Molodensky | DatumShiftPreferencesEx.BitFlag.BursaWolfe;
prefsEx.OnlyGoThruIntermediate = false;
There is one more step we must take before we will be ready to use the GetValidDatumShifts method: we must construct a DatumShiftInfoSetCollection object to hold the result of the method:
Dim shiftSets As New DatumShiftInfoSetCollection
DatumShiftInfoSetCollection shiftSets = new DatumShiftInfoSetCollection();
Now we are ready to find our DatumShifts:
If Not gcDataSource.GetValidDatumShifts(ct.SourceCoordSys, ct.TargetCoordSys, prefsEx, shiftSets) Then
MessageBox.Show("GetValidDatumShifts failed")
End If
if(! gcDataSource.GetValidDatumShifts(ct.SourceCoordSys, ct.TargetCoordSys, prefsEx, shiftSets))
{
MessageBox.Show("GetValidDatumShifts failed");
}
We now have a DatumShiftInfoSetCollection that is full of some number of DatumShiftInfoSets, each of which is full of some number of DatumShiftInfo objects. Each DatumShiftInfoSet represents a complete set of DatumShifts that will shift from our CoordTransform's SourceCoordSys to its TargetCoordSys. Each DatumShiftInfo object contains all of the information necessary to get a DatumShift from the DataSourceComponent. We are now presented with the task of determining which DatumShiftInfoSet should be used to populate our CoordTransform::DatumShifts property, and this task is outside the scope of this tutorial. For this lesson, let's just use the first DatumShiftInfoSet in the collection:
Dim dsiSet As DatumShiftInfoSet = shiftSets.Item(0)
Dim dsi As DatumShiftInfo
For Each dsi In dsiSet
Dim ds As DatumShift
ds = gcDataSource.GetDatumShift("GC", dsi.Code)
ds.ReverseUsage = dsi.ReverseUsage
ds = ct.DatumShifts.AddBack(ds)
Next
DatumShiftInfoSet dsiSet = shiftSets.get_Item(0);
foreach(DatumShiftInfo dsi in dsiSet)
{
DatumShift ds = gcDataSource.GetDatumShift("GC", dsi.Code);
ds.ReverseUsage = dsi.ReverseUsage;
ds = ct.DatumShifts.AddBack(ds);
}
Our CoordTransform now has all of the DatumShifts it will need to perform the transformation. For more information about using CoordTransforms, see Lesson 7 and Lesson 8.
The DatumShiftPicker dialog provides a graphical interface that accomplishes the same task as the GetValidDatumShifts method. You supply the dialog with the source and target CoordSys objects as well as a DatumShiftPreferencesEx object, and it finds all of the DatumShifts that meet those criteria. Once the DatumShifts are found, they are displayed to the users so that the user can select which ones will work best. The selected DatumShift objects are then put into a DatumShiftCollection for use by the user.
As with the previous methods, let's start by constructing a CoordTransform object. We will go into more depth about the CoordTransform object in Lesson 7 and Lesson 8.
Dim source As CoordSys = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E")
Dim target As CoordSys = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system")
Dim ct As New CoordTransform(source, target)
CoordSys source = gcDataSource.GetProjectedCoordSys("BMG", "ME-27E");
CoordSys target = gcDataSource.GetGeodeticCoordSys("BMG", "WGS84_coordinate_system");
CoordTransform ct = new CoordTransform(source, target);
Now we must construct a DatumShiftPreferencesEx object that describes the nature of the DatumShifts that we want. Let's suppose we are interested in DatumShifts that use either the Molodesky or Bursa-Wolfe method, and that we don't care if the DatumShifts use an intermediate HorizontalDatum, or if the Envelopes match. Then we would define our DatumShiftPreferencesEx like this:
Dim prefsEx As New DatumShiftPreferencesEx
prefsEx.BitFlags = DatumShiftPreferencesEx.BitFlag.Molodensky Or DatumShiftPreferencesEx.BitFlag.BursaWolfe
prefsEx.OnlyGoThruIntermediate = False
DatumShiftPreferencesEx prefsEx = new DatumShiftPreferencesEx();
prefsEx.BitFlags = DatumShiftPreferencesEx.BitFlag.Molodensky | DatumShiftPreferencesEx.BitFlag.BursaWolfe;
prefsEx.OnlyGoThruIntermediate = false;
We now have enough information to construct the DatumShiftPicker dialog. The constructor requires four arguments, the first of which is an instance of the DataSourceComponent, the second of which is the source CoordSys for the desired DatumShifts, the third of which is the target CoordSys for the desired DatumShifts, and the fourth of which is the DatumShiftPreferencesEx object that describes the nature of the desired DatumShifts.
Dim picker As New DatumShiftPicker(gcDataSource, ct.SourceCoordSys, ct.TargetCoordSys, prefsEx, Me.Handle)
DatumShiftPicker picker = new DatumShiftPicker(gcDataSource, ct.SourceCoordSys, ct.TargetCoordSys, prefsEx, this.Handle);
Once it has been constructed, the DatumShiftPicker will not be displayed until we call the Show method. The Show method requires a single argument, which is the DatumShiftCollection that will hold the DatumShifts that the user selects, and it returns a member of the DialogState enumeration that indicates the result of showing the dialog. Here is how we show the dialog:
Dim selectedShifts As New DatumShiftCollection
Dim retVal As DialogState
retVal = picker.Show(selectedShifts)
If retVal = DialogState.Success Then
ct.DatumShifts = selectedShifts
End If
DatumShiftCollection selectedShifts = new DatumShiftCollection();
DialogState retVal = picker.Show(ref selectedShifts);
if(retVal == DialogState.Success)
{
ct.DatumShifts = selectedShifts;
}
Here is an example of the appearance of the DatumShiftPicker dialog:
If the return value is either NoShiftNeeded or NoChoices, then the dialog was not ever shown. The return value NoShiftNeeded indicates that the dialog was not shown because there was no DatumShift required to perform the CoordTransform. This can occur when both the SourceCoordSys and the TargetCoordSys use the same HorizontalDatum. The return value NoChoices indicates that a DatumShift is required for the CoordTransform, but a suitable DatumShift could not be found in the DataSourceComponent. This can occur if the SourceCoordSys and TargetCoordSys use user-defined HorizontalDatum for which there are not DatumShifts. If the return value is Cancel, then the user clicked the Cancel button and no DatumShifts were selected. If the return value is Success, then the dialog was displayed, the user selected some DatumShifts, and the selected DatumShifts were put into the DatumShiftCollection passed to the Show method.
The DatumShiftPicker dialog also provides the option of choosing to not to apply any DatumShifts to the CoordTransform. This option can be selected by choosing "None" in the Category Pane of the DatumShiftPicker. Users should be aware that some coordinate shift may occur when shifting between ProjectedCoordSys' even though no DatumShift is being used. This can be occur if the source and target HorizontalDatums use different Ellipsoids.
Finally, we must clean up after ourselves and free the memory that was allocated in this lesson using the Dispose method:
ct.Dispose()
source.Dispose()
target.Dispose()
prefs.Dispose()
prefsEx.Dispose()
picker.Dispose()
selectedShifts.Dispose()
gcDataSource.Dispose()
ct.Dispose();
source.Dispose();
target.Dispose();
prefs.Dispose();
prefsEx.Dispose();
picker.Dispose();
selectedShifts.Dispose();
gcDataSource.Dispose();