File : README.WIN32.txt - Jan 22, 2009 Index: ====== PREAMBLE - General information about the suite of Atlas/Map applications. BUILDING - Building Atlas/Map with MSVC, in native WIN32 RUNNING - Running the Atlas/Map application, with FlightGear HELP - Brief help on the Atlas/Map applications. PREAMBLE - Atlas/Map ==================== SUITE OF APPLICATIONS - Atlas/Map This is a native WIN32 port of the Atlas/Map applications. Home page :- http://atlas.sourceforge.net/ Atlas is developed as open source under the GNU General Public License (GPL). The Atlas source is available via CVS, and some binaries are also available. - Atlas ------- The Atlas 'viewer' has several purposes rolled into one application. 1 - To read FlightGear data, and generate an image showing all the navigation aid within the boundaries of the display. The display can be zoomed in (+), or out (-), thus the actual area displayed depends on the current zoom level. 2 - Read png 'maps' generated by the Map application. If these are not available, and it is given the path to run Map, then it will generate these 'maps' automatically. 3 - Read data transmitted by FlightGear via UDP, when run with the --udp[=port] command, or read the COM port for data, from say a GPS device. 4 - Keep a 'track' of the flight in FlightGear, and display that 'track' on the map, and show a graph of certain parameters, altitude, speed, climb rate. 5 - Load, and display a previously saved 'track', for review purposes. - Map ----- The 'map creator' application reads FlightGear world data and generates 'maps' from it, the resolution depending on the size chosen. The default size is 256x256 for 'normal' resolution, and 64x64 for low resolution. These 'maps' can be in PNG or JPEG format, and generally cover a 1x1 degree grid. There is also a MapPS, which will generate a 'post script' format file, but this port has not been tested. The important issue is the 'size'. If map is used to generate 256x256 sized maps, then this is the default for Atlas. If higher resolution maps, say 512, or 1024 are generated, then Atlas must be given the same size ... - GetMap -------- GetMap is a separate distinct application, which uses the curl library for communications, and will fetch maps from Web Map Services (WMS). WMS servers are a Web Service. There is a lot to understand about these service, and you can start by reading :- http://en.wikipedia.org/wiki/Web_Map_Service As can be read, while it is normally associated with fetching an 'image' - PNG, GIF or JPEG, some also will return the actual raw data. The 'maps' retrieved from a WMS can be used in place of the 'maps' generated from the FlightGear data, but care must be taken about the 'size'. Unless given otherwise Atlas defaults to a size of 256x256, while for example, the NASA WMS is normally 512x512, but this just means adding a --size=512 when running Atlas using these 512x512 maps fetched from say http://wms.jpl.nasa.gov/wms.cgi ... BUILDING - Atlas/Map ==================== To build with Microsoft Visual C/C++ load and allow conversion of the Atlas.dsw file in this folder to the version being used. Note, although these are MSVC6 not all components, most notably SimGear, can be built with this OLD version, but all later versions MSVC7.1 (2002), MSVC8 (2005), MSVC9 (2008), and perhaps subsequent have no problems. There may exist an old Atlas.sln, and other old vcproj files, but these may be out of date, and need some fixes. The recommended build files are :- Atlas.dsw - atlas-win.dsp, Atlas.dsp, GetMap.dsp. Map.dsp, MapPS.dsp all in this build/msvc folder. The prerequisite libraries, and path are all established relative to this 'build/msvc' path in the Atlas root folder. If you have built these prerequisite items in other places, then the include directories, and additional library directories will need to be adjusted. Below is the current include and additional library directories, and libraries included. The GetMap project additionally requires the 'curl' library, but this project can be EXCLUDED if you just want to run Atlas/Map with FlightGear. Also the MapPS project has not been tested during this build. For native WIN32 this folder also includes the source of a static atlas-win.lib, to provide some functions, and other utilities, missing in the native RUNTIME libraries. This project is compiled using the 'Multi-threaded DLL' (/MD) runtime, and /MDd for Debug, and all the prerequisites MUST be compiled with the SAME runtime, or else you will get copious warnings, or even errors, on the LINKS ... Note each of these directories is relative to the location of the DSP files, which will be converted to VCPROJ file, but absolute directory paths can be used. Release Atlas/Map Include Directories: . ..\..\.. ..\..\..\zlib-1.2.3 ..\..\..\SimGear ..\..\..\lpng ..\..\..\OpenSceneGraph\include ..\..\..\freeglut\include ..\..\..\jpeg-6b And for GetMap: . ..\..\..\curl\include Atlas/Map 'Release' Linker List: ws2_32.lib sg.lib pui.lib ul.lib fnt.lib net.lib puAux.lib SimGear.lib libpng.lib zlib.lib libjpeg.lib These libraries may have a 'd', or '_d' appended for Debug. with Library paths: ..\..\..\lpng ..\..\..\zlib-1.2.3 ..\..\..\PLIB ..\..\..\SimGear\Release ..\..\..\freeglut\ReleaseStatic ..\..\..\jpeg-6b\lib And for GetMap: ws2_32.lib Wldap32.lib Winmm.lib Lib_curl.lib with library paths: ..\..\..\curl\build\Release RUNNING - Atlas/Map ==================== - Colour Palette File ---------------------- Both Atlas and Map need to be pointed to a palette file. This palette file contains a 'Colour' index, assigned a r,g,b,a values, and a set of 'Materials', each assigned to an index color, so you can personalise the colors used to generate maps. This folder also contains such a file called AtlasPalette.txt, but you can customise it to what you like. There is also a default AtlasPalette file in the Atlas 'src' directory, but if this is used, and you use --verbose, then there will be lots of 'materials' found in the scenery that issue a warning, since there is no corresponding index in this default file. These files also contain some 'help' comments. This folder also contains an AtlasPalette.txt file, which does contain mappings for the know materials found in the current FlightGear data. - GetMap --------- GetMap is not really needed for the Atlas/Map combination. It provides a way to fetched 'maps' from Web Map Servers (WMS). There is a testgm.bat batch file, using the NASA WMS to retrieve maps of the San Francisco area. This is really only of interest to compare and contrast with the maps generated from the FlightGear world data set. - Map ----- There is a testmap.bat file, with paths set relative to this folder, and assumes you have added the FG base data to ..\..\..\data. It you have used other path arrangments then testmap.bat USER VARIABLES will need to be adjusted. The test will only output ONE specific PNG file, given on the command line. But map can also be run in like an auto-mode, where it will generate maps for ALL the necessary areas that exist in the FG scenery data you point it at. Be aware, if you have done the massive download, and unpack of _ALL_ the FG world data, then Map will take a day or more to generate all the maps! But running map first to generate the map is not really required, since, Atlas, if given runtime access the map.exe, will proceed to automaitically generate all the required maps. Again, care should be taken as to what data path you pass to Atlas, because again, if it is the 'whole world' then Atlas will spend all day running map.exe, generating the maps, one by one ... - Altas ------- There is a testatlas.bat file, with paths set ralative to this folder, and assumes you have also added at least the FG base data to ..\..\..\data If you have used other paths, then testatlas.bat USER VARIABLES need to be adjusted accordingly. The test is centered on San Francisco, KSFO. You must supply a directory, either empty or where you want the generated maps to be placed. Some put this in their FG data folder, under Scenery, but it can be anywhere. Also the test batch file includes the important parameter :- --udp[=port] - default port is 5500 This causes Atlas to setup on the port, waiting for FlightGear data packets to arrive. The default is to check for data each second by default, but this can be set by the --update= command. As mentioned above, map.exe does not need to be run first to generate maps for Atlas to use, but you must supply a folder for this test batch file. (a) Atlas works without maps anyway, but the display is a little less interesting, but airports, navaids, etc are shown; (b) if given the path the the map.exe, or map.exe is copied to a path in your PATH environment variable, then Atlas will generate it own maps, but you MUST create the folder to hold these maps, with a sub-directory called 'lowres', if you want low resolution maps to also be generated. But take care - if you pass Atlas a whole world of FG data, then Atlas will merrily spend all day generating maps ;=(). When Atlas is running, and usually after it has finished generating any maps, using map.exe, it is time to run FlightGear. The only extra command that needs to be added to flightgear is :- --atlas=socket,out,5,localhost,5500,udp This command will cause FG to output 'Atlas' data on port 5500 5 times a second. This is more than sufficient to 'feed' Atlas with the aircraft information. This data is about 160 bytes long, of the form - $GPRMC,200843,A,3736.813,N,12221.435,W,000.0,297.9,1701109,0.000,E*58 $GPGGA,200843,3736.813,N,12221.435,W,1,,,04,F,,,,*0A $PATLA,111.70,280.0,111.70,280.0,0*54 Those of you with GPS instruments will recognise this data form. The data is read, and decoded to form 'track' data. When this data is received by Atlas, press an 'f' key to select the first track, and you should see Atlas, or moving map perform ... Note, while FG is starting up, it will output 20 or more 'blanks', like $GPRMC,200838,A,0000.000,N,00000.000,E,000.0,000.0,1701109,0.000,E*48 $GPGGA,200838,0000.000,N,00000.000,E,1,,,00,F,,,,*1B $PATLA,111.70,280.0,111.70,280.0,0*54 Note the latitude and longitude is ZERO. Atlas has learned to try to 'ignore' these packets. When 'connected' to FlightGear, and you have used the 'f' key on Atlas to select a track, the red cross should change to a small aircraft shape, and move on the map as you fly in FlightGear. The +/- keys will zoom in and out from the map, and the 'c' key, will center the aircraft on the map. The Atlas 'Graph' window will show Altitude, Speed and Climb Rate. And as you fly around in FlightGear, your position will be shown, and a track drawn, and the above three values in the graphs will be updated. A 'q' key in Atlas will quit the application, and if there is an active track, then you will be prompted to save this 'track' to a file. Or you can save the track at any time with the 's' key, and load previous saved track with the 'o' key. There is a sample-track.txt file in this folder. Below is a copy of the help from Map and Atlas giving more details. Note particularly the keyboard inputs that can be used when running Atlas. HELP PAGES - Atlas/Map ====================== Map Help -------- MAP - FlightGear mapping utility Usage: --lat=xx.xx Start at latitude xx.xx (deg., south is neg.) --lon=xx.xx Start at longitude xx.xx (deg., west is neg.) --size=pixels Create map of size pixels*pixels (default 256) --scale=x Kilometers from top to bottom of map (default 100) --autoscale Automatically set scale to 1x1 degree tile --light=x, y, z Set light vector for shading --airport-filter=string Display only airports with id beginning 'string' --output=name Write output to given file name (default 'map.png') --fg-root=path Overrides FG_ROOT environment variable --fg-scenery=path Overrides FG_SCENERY environment variable --enable-airports Show airports --enable-navaids Show navaids --flat-shading Don't do nice shading of the terrain --atlas=path Create maps of all scenery, and store them in path --verbose Display information during processing --singlebuffer Use single buffered display --headless Don't display output (render into an off-screen buffer) --glutfonts Use GLUT built-in fonts --palette=path Set the palette file to use --smooth-color Make smooth color heights --jpeg Create JPEG images with default quality (75) --jpeg=integer Create JPEG images with specified quality --aafactor=integer Do antialiasing on image ( factor must be a power of two ) --version Output version, and exit. Atlas Help ---------- ATLAS - A map browsing utility for FlightGear Usage: Atlas [] ... --lat= Start browsing at latitude x (deg. south i neg.) --lon= Start browsing at longitude x (deg. west i neg.) --airport= Start browsing at an airport specified by ICAO code icao --path= Set path for map images --fg-root= Overrides FG_ROOT environment variable --glutfonts Use GLUT bitmap fonts (fast for software rendering) --geometry=x Set initial window size --softcursor Draw mouse cursor using OpenGL (for fullscreen Voodoo cards) --udp[=] Input read from UDP socket at specified port (defaults to 5500) --serial[=] Input read from serial port with specified device (defaults to /dev/ttyS0) --baud= Set serial port baud rate (defaults to 4800) --square Set square mode (map 1x1 degree area on the whole image) to be compatible with images retrieved by GetMap --fg-scenery= Location of FlightGear scenery (defaults to /Scenery-Terrasync) --map-executable= Location of Map executable (defaults to 'Map') --size= Create maps of size pixels*pixels (default 256) --lowres-size= Create lowres maps of size pixels*pixels (defaults to 0, meaning don't generate lowres maps) --max-track= Maximum number of points to record while tracking a flight (defaults to 2000, 0 = unlimited) --concurrency= Number of tiles to simultaneously update (defaults to 1, 0 = unlimited) --update= Check for position updates every x seconds (defaults to 1.0) --autocenter-mode Automatically center map on aircraft (default is to not auto-center) --version Print version number --help Print this help Atlas keyboard, when running ... +/- Zoom In/Out. A/a Toggle Airport show. C Toggle Auto Centering. c Center Map on Aircraft. D/d Toggle Hide/Show the info interface and the graphs window. F/f Select the next ('f') or previous ('F') flight track. J/j Toggle the search interface. N/n Toggle Show Navigation Aids. O/o Open a Flight Track File. q Quit, prompting for save of any active track. S/s Save Flight Track File. T/t Toggle Texturing. W/w Clear/Close the current track. No warning if the track is unsaved. U/u Un-attach (detach) Network, and restart tracking. V/v Toggle Show Names. Happy moving map ;=)) Geoff. January 23, 2009 EOF - README.WIN32.txt