|
DFLib
Release 1.0.0
|
DFLib is extremely new and has been downloaded by very few people so far. As a consequence, there are no "Frequently Asked Questions." But I expect that some questions will come up, and have tried to anticipate them.
DFLib is a library of algorithms to solve the geolocation problem for hidden transmitters given bearings-only measurements. Given a number of such measurements, DFLib provides methods to estimate the location of the transmitter.
DFLib was inspired by a program called "ELT DFer" by Jim Baremore, K5QQ. That program was designed for use by Search and Rescue volunteers who were looking for Emergency Location Transmitters in downed aircraft. It implemented the Fix Cut Average and Stansfield estimators of transmitter position in a Visual Basic program that displayed its results through the program "All Topo Maps" by iGage.
Unfortunately, several issues led me to write my own program independent of this well-used program. Since it was written in an old version of Visual Basic that is no longer available, and could not easily be ported to any recent vintage of that execrable language, even having access to the source was not particularly useful. While Jim had done a great deal of work getting ELT DFer written and used, he was not interested in open-sourcing it or distributing it widely outside of the search and rescue team of which he had been a member, primarily because supporting the code on a large scale would be vastly more work than he'd already done writing it in the first place. And finally, ELT DFer is written in Visual Basic, meaning it can only run on Microsoft platforms — and I am not now and will never be a Windows user. My goal, therefore, was to start from scratch, learn how to do the necessary computations, and to write a code that was as portable as possible.
In doing so, I learned a great deal more about bearings-only target location than I had ever known. I was also able to extend DFLib's capabilities beyond those of ELT DFer.
DFLib is written in standard C++, and can be built on any platform with a C++ compiler and the necessary third-party libraries. To date, DFLib has been compiled on Linux, FreeBSD and Windows. The only required third-party library is proj.4, the cartographic projections library, which is written in standard C and is available for Windows, any Unix variant, and Mac. Therefore, there is no real impediment for DFLib to be ported to Mac as well. But I don't have a Mac, so haven't done so.
DFLib is licensed under the GNU Public License Version 2. A copy of the license is included in the source code.
In short, you may download DFLib, use it, modify it and redistribute it under a very broad range of conditions. What you may not do is create proprietary versions of it that are not open-sourced. If you have any questions about whether your use of DFLib is consistent with the license, read the COPYING file carefully.
No. DFLib is a library of geolocation algorithms. It does not contain a driver program with a graphical user interface. There are only a few example command-line programs in the source directory. These include SimpleDF and testlsDF_proj. The former takes a rigidly-formatted input file of DF reports and produces textual output of the fixes. The latter is a test harness that takes a transmitter location on the command line and an input file of receiver locations and parameters, producing a randomly-generated set of DF reports and showing DFLib's prediction of the transmitter location. It can be used to get a feel for how wrong the answers can be in the presence of random bearing errors.
That said, I have written a program called "qDF" that uses DFLib and provides a graphical user interface and several different display methods, including APRS and Google Earth displays. It is not included with DFLib, but is available separately under the same open source license.
Currently, DFLib provides only four estimators. The "Fix Cut Average" estimator is the most naive, computing the intersection of bearing lines from every pair of receivers and averaging the location. The "Least Squares" estimator is a simple geometric estimator that minimizes the sum of squares of perpendicular distances from bearing line to target point. The "Stansfield" estimator is a maximum likelihood estimator that assumes small bearing error and long target-to-receiver distances in order to simplify the algebra to allow closed-form solution. The "Maximum Likelihood" estimator starts at the same formula as the Stansfield estimator, but does not make the small-angle/long-distance approximation. It therefore requires numerical solution.
Yes. Research into the solution of the geolocation problem for bearings-only target location is quite vigorous, and there are many methods with different properties. The four I implemented in DFLib are the simplest and oldest. Additional methods, including methods that take into account uncertainty in receiver location as well as bearing, are out there in the literature. I do intend to create a bibliography to go with DFLib, but haven't gotten around to it yet. See the documentation of the DFLib::ReportCollection class for some references. The individual methods in that class do have a few web links to papers on the subject.
Well, sorta. DFLib does all of its calculations using plane geometry. The underlying abstract class DFLib::Abstract::Report is the one actually used by DFLib::ReportCollection, and all the ReportCollection class cares about is that there is some consistent X-Y coordinate system used by reports for which it can get coordinates through the getReceiverLocation method of the report class.
It was intended that the use of abstract classes would allow more flexibility in the use of the library.
The DFLib::ReportCollection class expects only that every report given to it implements the DFLib::Abstract::Report interface. Primarily that means that the ReportCollection can expect Report objects to provide methods that return coordinates in some X-Y coordinate system, return report bearings in the appropriate range, compute a distance between a receiver and some other point, and so on.
By using only the abstract interface of a Report, the ReportCollection is very flexible and allows you, the library user, to pick the appropriate way to store reports, so long as you implement the required interface.
In my original planning for this library, I anticipated DFLib being used by applications that already had data structures for DF reports. In that case, if the application were already in C++ and the data structures were objects of some existing class, all that would be necessary to use the existing structure with DFLib would be to add an inheritance from the DFLib::Abstract::Report class and implement the interface. Those could then be passed as-is to the DFLib::ReportCollection::addReport method without any other changes to the existing application.
Whether this is going to be the way DFLib is used or not remains to be seen. In the end, I wound up writing my own new programs to use DFLib instead of retrofitting DFLib into existing programs.
While DFLib::ReportCollection is very general and assumes only a low-level interface for reports, I found that it was much more convenient to deal with a more elaborate, higher-level set of classes from applications. The DFLib::Proj namespace contains those classes, specifically DFLib::Proj::Point, DFLib::Proj::Report.
As currently written, DFLib::Proj::Point allows each point to have a "user coordinate system" that is supported by the proj.4 cartographic projections library. These include things like latitude/longitude coordinates and Universal Transverse Mercator Coordinates. The projection library is used to convert the user's coordinate system into an X-Y coordinate system usable by the ReportCollection class.
DFLib::Proj::Report is an implementation of DFLib::Abstract::Report that includes a DFLib::Proj::Point as the receiver location. Thus, one can enter reports in whatever coordinate system is in use by the person operating the receiver, and be consistent in the use of a single X-Y coordinate system by the ReportCollection class.
DFLib::ProjReportCollection is not actually in the DFLib::Proj namespace, but is a derived class of DFLib::ReportCollection. DFLib::ReportCollection never attempts to use any methods of a Report other than those included in the DFLib::Abstract::Report interface, and therefore its addReport method can take any object that derives from that interface. I found it convenient in applications, however, to have a version of a report collection that could be assured of having only DFLib::Proj::Reports in it. In its current incarnation, DFLib::ProjReportCollection is nothing more than a wrapper around a DFLib::ReportCollection that can only take DFLib::Proj::Report objects in its addReport method. My thinking was that at some point the ProjReportCollection might want to take advantage of methods of the DFLib::Proj::Report that were extensions of the abstract interface, and therefore it had to have only the right kinds of objects in it.
My graphical user interface for DFLib, qDF, subclasses the ProjReportCollection and makes heavy use of methods outside the abstract interface. To do this without having the specialized class would require all sorts of dangerous upcasts of pointers from abstract to concrete types.
The getXY method of the DFLib::Proj::Point class returns the Mercator coordinates of the point using the equator as the latitude of true scale. That is, when using DFLib::Proj::Report objects in the ReportCollection class, the X-Y coordinate system is the Mercator projection, whose coordinates are in meters. The proj.4 cartographic projections library is used to convert coordinates in the user's coordinate system to their Mercator coordinates.
Maybe. Maybe not.
The Mercator projection has a couple of desirable properties that made it attractive for a first cut. It is a conformal projection, meaning that angles between small lines in the projected coordinate system are the same as the angles between the corresponding lines on the ellipsoid. North is always vertical in this projection. And straight lines of any length and in any orientation on any part of the plane represent loxodromes or rhumb lines on the surface of the ellipsoid. A loxodrome is a curve that intersects all meridians of longitude at the same angle.
Radio waves do not propagate along loxodromes, so it can be argued that this is a poor choice. Radio waves propagate along curves that are more closely geodesics on the surface. But solving the geodesic problem is much more computationally intensive, and a geodesic departing a receiver at a given azimuth is tangent to the loxodrome departing the receiver at the same azimuth. The error becomes appreciable over distance, but so far my experience has shown that the distance required is much longer than those typically seen in VHF transmitter hunting. So far, I have found that this choice serves the purposes of VHF transmitter hunting fairly well.
DFLib does not actually care what X-Y coordinate system you use, or even if it's a conformal projection — only that the report objects in the collection return correct bearing data and X-Y coordinates.
A possible improvement to address the geodesic/loxodrome issue would be to use a gnomonic projection whose center is close to the area of interest. Straight lines on a gnomonic projection are very nearly geodesics (they are exactly geodesics when projecting a sphere, but only approximately geodesics when projecting an ellipsoid). But the gnomonic projection is not conformal, and so computing the straight line corresponding to a given azimuth is not as simple as drawing a line that makes that angle with the local direction of North. One would have to solve the "forward geodesic problem" to compute the endpoint of the geodesic departing the receiver at the specified azimuth, then use the angle made by the straight line between those points in the gnomonic projection as the "bearing" in DFLib's calculations, and then do everything else in plane geometry as before. If this sounds like a lot of work, you now understand why I have not implemented that. But the DFLib abstract report classes are set up in such a way that it would not be difficult to implement this improvement should it prove necessary.
For a nice discussion of the errors involved in using projected coordinate systems as a basis for DF computations, see Houston, R.S. and Nelson,Model Error and the Direction-Finder Problem, J, IEEE Transactions on Aerospace and Electronic Systems, Volume AES-16, Number 5, pages 729-732.
1.8.9.1